# Building with Shipyard ⛴

Shipyard is a managed Build Service environment that VMware teams can use to build their applications. It also available for testing, demos and experimentation with Build Service.

***Note***: Please don’t share this environment or your access creds externally because hosted build service is not covered by a EULA or export control. To access, follow these steps:

#### Accessing shipyard

gcloud auth login 
gcloud container clusters get-credentials shipyard --region us-central1-c --project cf-build-service-prod

## Getting started

1. Get access to your team members that have @pivotal.io or @vmware.com email address

> Note: You can add a vmware.com email as an alternative email address to another gcp account.

1. Request access in #tanzu-build-service slack

> You can request access for a set of emails or for an entire google group.

1. Install the [gcloud cli](https://cloud.google.com/sdk/docs#install_the_latest_cloud_tools_version_cloudsdk_current_version)

## Creating your namespace(s)
1. Access Shipyard

Authorize your gcloud account with your gcp account.

    gcloud auth login 

Getting access to the shipyard cluster.

    gcloud container clusters get-credentials shipyard --region us-central1-c --project cf-build-service-prod

2. Create a "Project"

kubectl create -f

    apiVersion: projects.vmware.com/v1alpha1
    kind: Project
    metadata:
        name: my-team-namespace
    spec:
       access:
       - kind: User
         name: [e-mail]
       - kind: User
         name: [e-mail]

*What does this do?* This will create a namespace with the name "my-team-namespace". The access list configures a list of users that have access to the namespace.

3. Get the `kp` cli.

[Get the kp cli from the latest Tanzu Build Service release](https://network.pivotal.io/products/build-service/)

## Creating an Image

1. Choose a builder to build your application with:

Shipyard includes a set of pre-built cluster builders that the Build Service team maintains and keep up-to-date.

You can view available builders with:

    kp clusterbuilder list

To learn which buildpacks are in a specific builder run:

    kp clusterbuilder status <builder-name>

2. Add credentials for kpack to build your image

The best way to setup credentials is with kp

    kp secret create --help

Note: Make sure to create a secret in your namespace. Add `-n <your-namespace-name>` to kp or kubectl commands

You can also change your current namespace with: `kubectl config set-context --current --namespace=<your-namespace>`

3. Create an image resource.

The easiest way to get started is with kp:

    kp image create --help

You can also `kubectl apply -f` an image configuration:

    apiVersion: kpack.io/v1alpha1
    kind: Image
    metadata:
        name: sample-2
        namespace: my-team-namespace
    spec:
      tag: gcr.io/my-project/my-image
      builder:
        kind: ClusterBuilder
        name: base # your builder name
      source:
        git:
          url: https://github.com/buildpack/sample-java-app.git
          revision: 0eccc6c2f01d9f055087ebbf03526ed0623e014a

4. Check out your build logs

    kp build logs <image-name>

5. Check out your build history

    kp build list <image-name>

## Using Shipyard with Concourse

If you would like to use Shipyard with concourse we recommend the [concourse kpack resource](https://github.com/pivotal/concourse-kpack-resource)

To use the concourse kpack resource with shipyard you will need to create and authorize a service account to be used with shipyard.

1. Create a Service Account in your gcp account.

> No permissions are needed on this service account.

2. Contact us in #tanzu-build-service account for us to authorize the service account’s email

3. Add your service account's email to your project as a user.

    kubectl edit project <my-project-name>

Or re-apply your project configuration with the added service account email:

    kubectl apply -f project.yaml

The updated project should include the service account as User under inside the access list.

      - kind: User
        name: [e-mail]

> Note: Make sure to include the service account as a "User".

4. Configure the kpack concourse resource to use your service account.

    resources:
    - name: order-service-image
      type: kpack-image
      source:
        image: "some-existing-image-name"
        namespace: "some-namespace"

        gke:
          json_key: ((your-json-service-account-key))
          
          kubeconfig: ((shipyard-kubeconfig))

The shipyard-kubeconfig to use is provided below. You do not need to edit this to use shipyard and should use it unmodified.

apiVersion: v1
kind: Config
current-context: my-cluster
contexts: [{name: my-cluster, context: {cluster: cluster-1, user: user-1}}]
users: [{name: user-1, user: {auth-provider: {name: gcp}}}]
clusters:
- name: cluster-1
  cluster:
    server: "https://34.71.146.206"
    certificate-authority-data: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURLekNDQWhPZ0F3SUJBZ0lSQU8vWktkbC92aS93OHoyMFIrSFM0OWN3RFFZSktvWklodmNOQVFFTEJRQXcKTHpFdE1Dc0dBMVVFQXhNa05UTmpPVGhsWlRFdE16WXhPUzAwWXpJMUxUbGhNRGd0TXpVM01qRmtOR00xTWpJdwpNQjRYRFRJd01Ea3dNakUwTkRjek9Wb1hEVEkxTURrd01URTFORGN6T1Zvd0x6RXRNQ3NHQTFVRUF4TWtOVE5qCk9UaGxaVEV0TXpZeE9TMDBZekkxTFRsaE1EZ3RNelUzTWpGa05HTTFNakl3TUlJQklqQU5CZ2txaGtpRzl3MEIKQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBOHQyVHFvYllJMlhTRjhvZGQ3dElhUzlXT2lPRVJmWE9wQU9oZ3hyWApabWc1Vk04amZiUTZ0YWxKVFZTZ3ZDOHExcjZ0MzlQSGJld3BvTVFBUzB0OFRkeHdONFVxWFJ4b0dURVRDRkJZCk9oZUdEelAySHlnS0hZTG4rdDFRTHUyMm5EY2V0Zk8vKzBGK2VIZ0RaaXoyMFFKUm0yeUkvZURtZHJDRkRaOGEKTFlsMmJINHZnRkdxQ0c3V2pvUlpXbEdaMUpUQXEvRG5nbVJFaGlIdmJhM1VLWktHem5JL0dtN1ZzdXlyKzh2Rwpwa0JIYTFCWDFyZHV4ZnFFYlRLclFSbnAxazQ2Y2VqdWN4ZktMd04zclE1cjNGT2dRd1UyTG96RmYvNHdEdGtBCm5ENGJkT0VyR2l3UDNSZXJoMG1kOFNBblpLWXFsWTV3dXNKdEduLzdYeWQwR3dJREFRQUJvMEl3UURBT0JnTlYKSFE4QkFmOEVCQU1DQWdRd0R3WURWUjBUQVFIL0JBVXdBd0VCL3pBZEJnTlZIUTRFRmdRVTdIa3IyOGdkbnQ1ZAozaGZVVFEvMlNWRm9zL0l3RFFZSktvWklodmNOQVFFTEJRQURnZ0VCQU1Wdjh4clBFMXZRa1ZrUVh0YUovNUV2CkZ0RFY0MzdBUzBUdWhIdnM3UllpMlBrTTM3OFhyYkxleXlpNHFlNi9zT0VGMDBHaFJzb204cU1JYld2Nlk2MmgKRFJpSjF4NnNucTFaQ0tHbHZDc1ZnRU5pamNiYWYwZjMrRzd1OTNPSldEdWl4Nlhmb3RpaFM0dS9VNWJMK3pwWQpnN2RSYXM0SnZvcC9FZWdNZG9kZWcyckczOHhlOHVjRGZaNFZNM3RORURPSVZZalQxblNsSmlRZFVON0dYS0hXCkczL0doQ1ZQbU9xU1N6YzRQNFVJTm91aHJMZU1ncXBnSVp0d2hleFFHZGFyVnBlSmUvMjRxemhTSlFSRENjdjkKeEVWVUZTSDU4eU8zY3FlanVtU09ScHRkajZicHNxaWhTT3lUM20rcXVsZ1REZUkxakRsNnZRL0RGMzhvaGFzPQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg=="

*What is going on here?* This is the configuration for shipyard that allows the concourse resource to authenticate with your json-service-acounnt-key. We generated this by following [this blog post](https://ahmet.im/blog/authenticating-to-gke-without-gcloud/).

## Using the Paketo Ruby Buildpack on Shipyard

The [Paketo Ruby buildpack](https://github.com/paketo-buildpacks/ruby) is provided on Shipyard but, not included in the provided cluster builders. Users will need to create their own builder to utilize the Ruby Buildpack. This process is simple and described below:

1. Add credentials for kpack to build your builder. If you already created a registry secret in your namespace you can skip this step.

The best way to setup credentials is with kp

    kp secret create --help

Note: Make sure to create a secret in your namespace. Add `-n <your-namespace-name>` to kp or kubectl commands.

2. Create a builder configuration that uses the ruby buildpack.

Use `kubectl apply -f` the create a builder configuration:

    apiVersion: kpack.io/v1alpha1
    kind: Builder
    metadata:
        name: ruby-builder
        namespace: my-team-namespace
    spec:
      tag: my-registry.io/my-project/my-image
      order:
      - group:
        - id: paketo-buildpacks/ruby
      stack:
        kind: ClusterStack
        name: full
      store:
        kind: ClusterStore
        name: default

3. Use the builder with your image configuration.

Reference the builder `ruby-builder` created in step #2 in your image configuration.

The easiest way to set your builder is with kp:

    kp image patch my-image-name --namespace my-namespace --builder ruby-builder 

## FAQ

**Q:** Where can I get documentation on using the kp cli?

Review our [documentation](https://docs.pivotal.io/build-service/1-0/index.html) to get started. Ask questions in #tanzu-build-service. Feedback welcome!

**Q:** How do I add someone to my shipyard project?

Add a “kind: User” with the pivotal or vmware email address to the project.

kubectl edit <your-project-name>

**Q:** Will Shipyard be updated with new buildpacks and stack versions?

The TBS team will centrally manage the cluster store and the cluster stack(s) and introduce new versions of the stack and new versions of buildpacks as they become available

**Q:** What builders are available?

Three builders with three different stacks are currently available.
* `full` - A "large" Ubuntu 18.04 based stack
* `base` - A "minimal" Ubuntu 18.04 based stack
* `tiny` - A Ubuntu 18.04, similar to distroless.

*Note:* The Base & Full builders include buildpacks for Java, .NET, NodeJS, Golang, PHP, HTTPD and NGINX. The Tiny builder provides Buildpacks for Golang, and Java Native Image applications.

**Q:** What permissions will I have in Shipyard?

All accounts provisioned by the TBS team will have non-admin permissions

You will not be able to:
* Create or modify cluster scoped builders (you can, however, create namespace scoped builders).
* Create or modify the buildpacks in the clusterstore resource.
* Create or modify the stacks used by this deployment of TBS.

**Q:** How can I access the Shipyard cluster with service account credentials?
1. Create a Service Account on your gcp account.
1. Contact us in #tanzu-build-service account for us to authorize the service account’s email
1. Use `gcloud auth activate-service-account --key-file <service-account-key.json>`

**Q:** What should I not forget to do?

Don’t forget to provide the product team with feedback in #tanzu-build-service!