Installing Tanzu Build Service

--- title: Installing Tanzu Build Service owner: Build Service Team --- This topic describes how to install and configure Tanzu Build Service. ## <a id='overview'></a> Overview Build Service can be installed on any Kubernetes cluster (v1.16 or later) including TKGI (formerly PKS), GKE and AKS clusters. The installation instructions are divided between the TKGI installation, which uses OpenID Connect (OIDC) for authentication, and the install on other hosted Kubernetes clusters. ## <a id='prerequisites'></a> Prerequisites Before you install Build Service, you must: * Have access to the Kubernetes cluster satisfying the [minimum required permissions](#install-rbac). * Ensure your Kubernetes cluster is configured with default `StorageClass`. Tanzu Build Service will default to using 2G of cache if a default `StorageClass` is defined. Build Service utilizes `PersistentVolumeClaims` to cache build artifacts, which reduces the time of subsequent builds. For more information, see [Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) in the Kubernetes documentation. And for information on defining a default StorageClass, see [Changing the default StorageClass](https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/) * Download three [Carvel](https://carvel.dev/) CLIs for your operating system. These can be found on their respective Tanzu Network pages: - [kapp](https://network.pivotal.io/products/kapp/) is a deployment tool that allows users to manage Kubernetes resources in bulk. - [ytt](https://network.pivotal.io/products/ytt/) is a templating tool that understands YAML structure. - [kbld](https://network.pivotal.io/products/kbld/) is tool that builds, pushes, and relocates container images. * Download the Build Service Bundle from the [Tanzu Build Service](https://network.pivotal.io/products/build-service/) page on Tanzu Network. * Unarchive the Build Service Bundle file: ``` tar xvf build-service-<version>.tar -C /tmp ``` * Download the kp CLI for your operating system from the [Tanzu Build Service](https://network.pivotal.io/products/build-service/) page on Tanzu Network. * Download the Dependency Descriptor file (`descriptor-<version>.yaml`) from the latest release on the [Tanzu Build Service Dependencies](https://network.pivotal.io/products/tbs-dependencies/) page on Tanzu Network ## <a id='other-install'></a> Installing on TKG/GKE/AKS Create a kubernetes cluster where you would like to install build service and target the cluster as follows: ``` kubectl config use-context <CONTEXT-NAME> ``` ### <a id='other-relocate-images'></a> Relocate Images to a Registry This procedure relocates images from the Tanzu Network registry to an internal image registry. 1. Log in to the image registry where you want to store the images by running: ``` docker login <IMAGE-REGISTRY> ``` Where `IMAGE-REGISTRY` is the name of the image registry where you want to store the images. 2. Log in to the Tanzu Network registry with your Tanzu Network credentials: ``` docker login registry.pivotal.io ``` 3. Relocate the images with the [Carvel](https://carvel.dev/) tool `kbld` by running: ``` kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository <IMAGE-REPOSITORY> ``` Where `IMAGE-REPOSITORY` is the repository in your registry that you want to relocate images to. Note: The flag argument <code>--lock-output /tmp/images-relocated.lock</code> creates a file that will be used for installation</code>. Note: When relocating, the IMAGE-REPOSITORY must be the IMAGE-REGISTRY appended with the destination repository for the images. For example, <code>IMAGE-REGISTRY/build-service</code>. Exception: When relocating to Dockerhub, you must provide the Dockerhub repository and an image name that kbld will use for relocation. For example, <code>my-dockerhub-account/build-service</code>. For example: * Dockerhub `kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository my-dockerhub-account/build-service` * GCR `kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository gcr.io/my-project/build-service` * Artifactory `kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository artifactory.com/my-project/build-service` * Harbor `kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository harbor.io/my-project/build-service` ### <a id='other-install'></a> Install Tanzu Build Service There are two ways to install Tanzu Build Service: 1. Using a public registry (eg. GCR, Dockerhub) or an internal registry that uses a trusted certificate (eg. Let's Encrypt) 2. Using an internal registry that uses a self-signed CA certificate (eg. Harbor, Artifactory) #### <a id='other-install-no-ca'></a> Install Tanzu Build Service Public Registry Use the [Carvel](https://carvel.dev/) tools `kapp`, `ytt`, and `kbld` to install Build Service and define the required Build Service parameters by running: ``` ytt -f /tmp/values.yaml \ -f /tmp/manifests/ \ -v docker_repository="<IMAGE-REPOSITORY>" \ -v docker_username="<REGISTRY-USERNAME>" \ -v docker_password="<REGISTRY-PASSWORD>" \ | kbld -f /tmp/images-relocated.lock -f- \ | kapp deploy -a tanzu-build-service -f- -y ``` Where: * `IMAGE-REPOSITORY` is the image repository where Tanzu Build Service images exist. Note: This is identical to the IMAGE-REPOSITORY argument provided during kbld relocation command. Exception: When using Dockerhub as your registry target, only use your DockerHub account for this value. For example, my-dockerhub-account (without /build-service). Otherwise, you will encounter an error similar to: <code>Error: invalid credentials, ensure registry credentials for 'index.docker.io/my-dockerhub-account/build-service/tanzu-buildpacks_go' are available locally</code> * `REGISTRY-USERNAME` is the username you use to access the registry. `gcr.io` expects `_json_key` as the username when using JSON key file authentication. * `REGISTRY-PASSWORD` is the password you use to access the registry. Note: [Secrets in Tanzu Build Service](secrets-in-tbs.html) for more information about how the registry username and password are used in Tanzu Build Service. #### <a id='other-ca-cert'></a> Installing with a CA certificate for internal registry To install Tanzu Build Service with an internal registry that requires providing a CA certificate such as Harbor, use the normal installation command with the CA certificate file passed in with a `-f` flag: ``` ytt -f /tmp/values.yaml \ -f /tmp/manifests/ \ -f <PATH-TO-CA> \ -v docker_repository="<IMAGE-REPOSITORY>" \ -v docker_username="<REGISTRY-USERNAME>" \ -v docker_password="<REGISTRY-PASSWORD>" \ | kbld -f /tmp/images-relocated.lock -f- \ | kapp deploy -a tanzu-build-service -f- -y ``` Where: * `PATH-TO-CA` is the path to the registry root CA. This CA is required to enable Build Service to interact with internally deployed registries. This is the CA that was used while deploying the registry. * `IMAGE-REPOSITORY` is the image repository where Tanzu Build Service images exist. Note: This is identical to the IMAGE-REPOSITORY argument provided during kbld relocation command. Exception: When using Dockerhub as your registry target, only use your DockerHub account for this value. For example, my-dockerhub-account (without /build-service). Otherwise, you will encounter an error similar to: <code>Error: invalid credentials, ensure registry credentials for 'index.docker.io/my-dockerhub-account/build-service/tanzu-buildpacks_go' are available locally</code> * `REGISTRY-USERNAME` is the username you use to access the registry. `gcr.io` expects `_json_key` as the username when using JSON key file authentication. * `REGISTRY-PASSWORD` is the password you use to access the registry. Note: [Secrets in Tanzu Build Service](secrets-in-tbs.html) for more information about how the registry username and password are used in Tanzu Build Service. ### <a id='other-import'></a> Import Tanzu Build Service Dependencies The Tanzu Build Service Dependencies (Stacks, Buildpacks, Builders, etc.) are used to build applications and keep them patched. These must be imported with the `kp` cli and the Dependency Descriptor (`descriptor-<version>.yaml`) file from the [Tanzu Build Service Dependencies](https://network.pivotal.io/products/tbs-dependencies/) page: ``` kp import -f /tmp/descriptor-<version>.yaml ``` Successfully performing a `kp import` command requires that your Tanzu Network account has access to the images specified in the Dependency Descriptor file. Currently, users can only access these images if they agree to the EULA for each dependency. Users must navigate to each of the dependency product pages in Tanzu Network and accept the EULA highlighted in yellow underneath the `Releases` dropdown. Here are the links to each Tanzu Network page in which users must accept the EULA: 1. [Tanzu Build Service Dependencies](https://network.pivotal.io/products/tbs-dependencies/) 1. [Java Buildpack for VMware Tanzu](https://network.pivotal.io/products/tanzu-java-buildpack/) 1. [Java Native Image Buildpack for VMware Tanzu](https://network.pivotal.io/products/tanzu-java-native-image-buildpack) 1. [Node.js Buildpack for VMware Tanzu](https://network.pivotal.io/products/tanzu-nodejs-buildpack/) 1. [Go Buildpack for VMware Tanzu](https://network.pivotal.io/products/tanzu-go-buildpack/) Note: `kp import` will fail if it cannot access the images in all of the above Tanzu Network pages. Note: You must be logged in locally to the registry used for `IMAGE-REGISTRY` during relocation and the Tanzu Network registry `registry.pivotal.io`. #### <a id='other-additional-config'></a> Additional Configuration Other optional parameters can be added using the `-v` flag: * `admin_users` is a comma separated list of users who will be granted admin privileges on Build Service. * `admin_groups`: a comma separated list of groups that will be granted admin privileges on Build Service. * `http_proxy`: The HTTP proxy to use for network traffic. * `https_proxy`: The HTTPS proxy to use for network traffic. * `no_proxy`: A comma-separated list of hostnames, IP addresses, or IP ranges in CIDR format that should not use a proxy. Note: When proxy server is enabled using <code>http_proxy</code> and/or <code>https_proxy</code>, traffic to the kubernetes API server will also flow through the proxy server. This is a known limitation and can be circumvented by using <code>no_proxy</code> to specify the kubernetes API server. ## <a id='tkgi-install'></a> Installing on TKGI (formerly PKS) * Install TKGI v1.7 or later. For more information, see [Installing Tanzu Kubernetes Grid Integrated Edition](https://docs.pivotal.io/tkgi/1-8/installing.html) in the TKGI documentation. * To install Build Service, you must configure a User Account and Authentication (UAA) client credentials. * Optional: configure your TKGI tile with `oidc` as described [here](#tkgi-as-oidc-provider). ### <a id='retrieve-credentials'></a> Retrieve TKGI Cluster Credentials This procedure retrieves the credentials that authenticate communication between `kubectl` and the TKGI cluster where Build Service runs. To retrieve the TKGI cluster credentials: 1. Log in to TKGI and get the latest kubeconfig by running: ``` tkgi get-kubeconfig CLUSTER-NAME -a API-URI -u USERNAME -p PASSWORD --ca-cert PATH-TO-CERTIFICATE ``` Where: * `API-URI` is the TKGI API server URI. * `USERNAME` is name of your cluster admin. * `PASSWORD` is the cluster admin password. * `PATH-TO-CERTIFICATE` is the path to your root CA certificate. * `CLUSTER-NAME` is the name of the TKGI cluster where Build Service runs. This command sets the context to the `CLUSTER-NAME` provided. For example: ``` tkgi get-kubeconfig build-cluster -a api.tkgi.example.com -u alana -p P4ssW0rd --ca-cert /var/tempest/workspaces/default/root_ca_certificate ``` ### <a id='tkgi-relocate-images'></a> Relocate Images to a Registry This procedure relocates images from the Tanzu Network registry to an internal image registry. 1. Log in to the image registry where you want to store the images by running: ``` docker login <IMAGE-REGISTRY> ``` Where `IMAGE-REGISTRY` is the name of the image registry where you want to store the images. 2. Log in to the Tanzu Network registry with your Tanzu Network credentials: ``` docker login registry.pivotal.io ``` 3. Relocate the images with the [Carvel](https://carvel.dev/) tool `kbld` by running: ``` kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository <IMAGE-REPOSITORY> ``` Where `IMAGE-REPOSITORY` is the repository in your registry that you want to relocate images to. Note: The flag argument <code>--lock-output /tmp/images-relocated.lock</code> creates a file that will be used for installation</code>. Note: When relocating, the IMAGE-REPOSITORY must be the IMAGE-REGISTRY appended with the destination repository for the images. For example, <code>IMAGE-REGISTRY/build-service</code>. Exception: When relocating to Dockerhub, you must provide the Dockerhub repository and an image name that kbld will use for relocation. For example, <code>my-dockerhub-account/build-service</code>. For example: * Dockerhub `kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository my-dockerhub-account/build-service` * GCR `kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository gcr.io/my-project/build-service` * Artifactory `kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository artifactory.com/my-project/build-service` * Harbor `kbld relocate -f /tmp/images.lock --lock-output /tmp/images-relocated.lock --repository harbor.io/my-project/build-service` ### <a id='tkgi-install'></a> Install Tanzu Build Service There are two ways to install Tanzu Build Service: 1. Using a public registry (eg. GCR, Dockerhub) or an internal registry that uses a trusted certificate (eg. Let's Encrypt) 2. Using an internal registry that uses a self-signed CA certificate (eg. Harbor, Artifactory) #### <a id='tkgi-install-no-ca'></a> Install Tanzu Build Service Public Registry Use the [Carvel](https://carvel.dev/) tools `kapp`, `ytt`, and `kbld` to install Build Service and define the required Build Service parameters by running: ``` ytt -f /tmp/values.yaml \ -f /tmp/manifests/ \ -v docker_repository="<IMAGE-REPOSITORY>" \ -v docker_username="<REGISTRY-USERNAME>" \ -v docker_password="<REGISTRY-PASSWORD>" \ | kbld -f /tmp/images-relocated.lock -f- \ | kapp deploy -a tanzu-build-service -f- -y ``` Where: * `IMAGE-REPOSITORY` is the image repository where Tanzu Build Service images exist. Note: This is identical to the IMAGE-REPOSITORY argument provided during kbld relocation command. Exception: When using Dockerhub as your registry target, only use your DockerHub account for this value. For example, my-dockerhub-account (without /build-service). Otherwise, you will encounter an error similar to: <code>Error: invalid credentials, ensure registry credentials for 'index.docker.io/my-dockerhub-account/build-service/tanzu-buildpacks_go' are available locally</code> * `REGISTRY-USERNAME` is the username you use to access the registry. `gcr.io` expects `_json_key` as the username when using JSON key file authentication. * `REGISTRY-PASSWORD` is the password you use to access the registry. Note: [Secrets in Tanzu Build Service](secrets-in-tbs.html) for more information about how the registry username and password are used in Tanzu Build Service. #### <a id='tkgi-ca-cert'></a> Installing with a CA certificate for internal registry To install Tanzu Build Service with an internal registry that requires providing a CA certificate such as Harbor, use the normal installation command with the CA certificate file passed in with a `-f` flag: ``` ytt -f /tmp/values.yaml \ -f /tmp/manifests/ \ -f <PATH-TO-CA> \ -v docker_repository="<IMAGE-REPOSITORY>" \ -v docker_username="<REGISTRY-USERNAME>" \ -v docker_password="<REGISTRY-PASSWORD>" \ | kbld -f /tmp/images-relocated.lock -f- \ | kapp deploy -a tanzu-build-service -f- -y ``` Where: * `PATH-TO-CA` is the path to the registry root CA. This CA is required to enable Build Service to interact with internally deployed registries. This is the CA that was used while deploying the registry. * `IMAGE-REPOSITORY` is the image repository where Tanzu Build Service images exist. Note: This is identical to the IMAGE-REPOSITORY argument provided during kbld relocation command. Exception: When using Dockerhub as your registry target, only use your DockerHub account for this value. For example, my-dockerhub-account (without /build-service). Otherwise, you will encounter an error similar to: <code>Error: invalid credentials, ensure registry credentials for 'index.docker.io/my-dockerhub-account/build-service/tanzu-buildpacks_go' are available locally</code> * `REGISTRY-USERNAME` is the username you use to access the registry. `gcr.io` expects `_json_key` as the username when using JSON key file authentication. * `REGISTRY-PASSWORD` is the password you use to access the registry. Note: [Secrets in Tanzu Build Service](secrets-in-tbs.html) for more information about how the registry username and password are used in Tanzu Build Service. ### <a id='tkgi-import'></a> Import Tanzu Build Service Dependencies The Tanzu Build Service Dependencies (Stacks, Buildpacks, Builders, etc.) are used to build applications and keep them patched. These must be imported with the `kp` cli and the Dependency Descriptor (`descriptor-<version>.yaml`) file from the [Tanzu Build Service Dependencies](https://network.pivotal.io/products/tbs-dependencies/) page: ``` kp import -f /tmp/descriptor-<version>.yaml ``` Successfully performing a `kp import` command requires that your Tanzu Network account has access to the images specified in the Dependency Descriptor file. Currently, users can only access these images if they agree to the EULA for each dependency. Users must navigate to each of the dependency product pages in Tanzu Network and accept the EULA highlighted in yellow underneath the `Releases` dropdown. Here are the links to each Tanzu Network page in which users must accept the EULA: 1. [Tanzu Build Service Dependencies](https://network.pivotal.io/products/tbs-dependencies/) 1. [Java Buildpack for VMware Tanzu](https://network.pivotal.io/products/tanzu-java-buildpack/) 1. [Java Native Image Buildpack for VMware Tanzu](https://network.pivotal.io/products/tanzu-java-native-image-buildpack) 1. [Node.js Buildpack for VMware Tanzu](https://network.pivotal.io/products/tanzu-nodejs-buildpack/) 1. [Go Buildpack for VMware Tanzu](https://network.pivotal.io/products/tanzu-go-buildpack/) Note: `kp import` will fail if it cannot access the images in all of the above Tanzu Network pages. Note: You must be logged in locally to the registry used for `IMAGE-REGISTRY` during relocation and the Tanzu Network registry `registry.pivotal.io`. #### <a id='tkgi-additional-config'></a> Additional Configuration Other optional parameters can be added using the `-v` flag: * `admin_users` is a comma separated list of users who will be granted admin privileges on Build Service. * `admin_groups`: a comma separated list of groups that will be granted admin privileges on Build Service. * `http_proxy`: The HTTP proxy to use for network traffic. * `https_proxy`: The HTTPS proxy to use for network traffic. * `no_proxy`: A comma-separated list of hostnames, IP addresses, or IP ranges in CIDR format that should not use a proxy. Note: When proxy server is enabled using <code>http_proxy</code> and/or <code>https_proxy</code>, traffic to the kubernetes API server will also flow through the proxy server. This is a known limitation and can be circumvented by using <code>no_proxy</code> to specify the kubernetes API server. ### <a id='tkgi-as-oidc-provider'></a> Configuring TKGI as an OIDC Provider The authentication and authorization processes for Build Service use a combination of RBAC rules and third-party authentication, including OpenID Connect (OIDC). You may configure UAA as an OIDC provider for your TKGI deployment to provide authentication for Build Service. To configure UAA as an OIDC provider for your TKGI deployment: 1. Navigate to the OpsManager Installation Dashboard. 1. Click the TKGI tile. 1. Select **UAA**. 1. Under **Configure created clusters to use UAA as the OIDC provider**, select **Enable**. 1. Ensure the values in the **UAA OIDC Groups Prefix** and **UAA OIDC Username Prefix** fields are the same and record them. For example, `"oidc:"`. You will need these values during the installation of Build Service. Note: Ensure you add a <code>:</code> at the end of the desired prefix. 1. Click **Save**. 1. In the OpsManager Installation Dashboard, click **Review Pending Changes**, then **Apply Changes**. ## <a id='offline-installation'></a> Installation to Air-Gapped Environment Tanzu Build Service can be installed to a Kubernetes Cluster and registry that are air-gapped from external traffic. An air-gapped environment will often use an internal registry with a self-signed CA certificate and you will need access to this CA certificate file to install TBS. Note: If you are using a CA certificate that is trusted (eg. Let's Encrypt) you will not need the CA certificate file. ### <a id='offline-relocate-images'></a> Relocate Images to a Registry (Air-Gapped) This procedure relocates images from the Tanzu Network registry to an internal image registry via a local machine. The local machine must have write access to the internal registry. 1. Log in to the image registry where you want to store the images by running: ``` docker login <IMAGE-REGISTRY> ``` Where `IMAGE-REGISTRY` is the name of the image registry where you want to store the images. 2. Log in to the Tanzu Network registry with your Tanzu Network credentials: ``` docker login registry.pivotal.io ``` 3. Package the images in a file on your local machine with the [Carvel](https://carvel.dev/) tool `kbld` by running: ``` kbld package -f /tmp/images.lock --output /tmp/packaged-images.tar ``` 4. Move the output file `packaged-images.tar` to a machine that has access to the air-gapped environment. 5. Unpackage the images from your local machine to the internal registry: ``` kbld unpackage -f /tmp/images.lock \ --input /tmp/packaged-images.tar \ --repository <IMAGE-REPOSITORY> \ --lock-output /tmp/images-relocated.lock \ --registry-ca-cert-path <PATH-TO-CA> ``` Where: * `IMAGE-REPOSITORY` is the repository in your registry that you want to relocate images to. * `PATH-TO-CA` is the path to the registry CA certificate file. Note: The flag argument `--lock-output /tmp/images-relocated.lock` creates a file that will be used for installation</code>. Note: When relocating to a registry that is not Dockerhub, the IMAGE-REPOSITORY must be the IMAGE-REGISTRY appended with the destination repository for the images. For example, <code>IMAGE-REGISTRY/build-service</code>. Exception: When relocating to Dockerhub, you must provide the Dockerhub repository and an image name that kbld will use for relocation. For example, <code>my-dockerhub-account/build-service</code>. For example: * Dockerhub `kbld unpackage -f /tmp/images.lock --input /tmp/packaged-images.tar --lock-output /tmp/images-relocated.lock --repository my-dockerhub-account/build-service --registry-ca-cert-path ca.crt` * GCR `kbld unpackage -f /tmp/images.lock --input /tmp/packaged-images.tar --lock-output /tmp/images-relocated.lock --repository gcr.io/my-project/build-service --registry-ca-cert-path ca.crt` * Artifactory `kbld unpackage -f /tmp/images.lock --input /tmp/packaged-images.tar --lock-output /tmp/images-relocated.lock --repository artifactory.com/my-project/build-service --registry-ca-cert-path ca.crt` * Harbor `kbld unpackage -f /tmp/images.lock --input /tmp/packaged-images.tar --lock-output /tmp/images-relocated.lock --repository harbor.io/my-project/build-service --registry-ca-cert-path ca.crt` ### <a id='offline-import'></a> Import Tanzu Build Service Dependencies (Air-Gapped) The Tanzu Build Service Dependencies (Stacks, Buildpacks, Builders, etc.) are used to build applications and keep them patched. These must be imported with the `kp` cli and the Dependency Descriptor (`descriptor-<version>.yaml`) file from the [Tanzu Build Service Dependencies](https://network.pivotal.io/products/tbs-dependencies/) page. #### <a id='offline-import-relocate'></a> Relocate Tanzu Build Service Dependency Images (Air-Gapped) To import these dependencies into an air-gapped environment, they must first be relocated to the internal registry. Use `kbld` to perform this relocation similarly to installation: 1. Download the dependency images locally: ``` kbld package -f descriptor-<version>.yaml \ --output /tmp/packaged-dependencies.tar ``` Note: You must be logged in locally to the Tanzu Network registry. 1. Move the output file `packaged-dependencies.tar` to a machine that has access to the air-gapped environment. 1. Upload the dependency images to the Tanzu Build Service registry: ``` kbld unpackage -f descriptor-<version>.yaml \ --input /tmp/packaged-dependencies.tar \ --repository <IMAGE-REPOSITORY> \ --lock-output /tmp/dependencies-relocated.lock \ --registry-ca-cert-path <PATH-TO-CA> ``` Where: * `IMAGE-REPOSITORY` is the internal image repository where dependency images will be relocated. * `PATH-TO-CA` is the path to the registry CA certificate file. Note: You must be logged in locally to the registry used for `IMAGE-REGISTRY`. #### <a id='offline-import-import'></a> Import Tanzu Build Service Dependency Resources (Air-Gapped) After the dependency images are uploaded to the internal registry, you can successfully import these images and create the corresponding Tanzu Build Service resources. Use the following command with `kbld` and the `kp` CLI: ``` kbld -f descriptor-<version>.yaml -f /tmp/dependencies-relocated.lock | kp import -f - ``` Note: If you receive a TLS error, you may need to add the registry CA certificate to your local machine's trusted certs. #### <a id='offline-ca-cert-install'></a> Installing (Air-Gapped) Use the [Carvel](https://carvel.dev/) tools `kapp`, `ytt`, and `kbld` to install Build Service and define the required Build Service parameters by running: ``` ytt -f /tmp/values.yaml \ -f /tmp/manifests/ \ -f <PATH-TO-CA> \ -v docker_repository="<IMAGE-REPOSITORY>" \ -v docker_username="<REGISTRY-USERNAME>" \ -v docker_password="<REGISTRY-PASSWORD>" \ | kbld -f /tmp/images-relocated.lock -f- \ | kapp deploy -a tanzu-build-service -f- -y ``` Where: * `PATH-TO-CA` is the path to the registry root CA. This CA is required to enable Build Service to interact with internally deployed registries. This is the CA that was used while deploying the registry. * `IMAGE-REPOSITORY` is the image repository where Tanzu Build Service images exist. Note: This is identical to the IMAGE-REPOSITORY argument provided during kbld relocation command. Exception: When using Dockerhub as your registry target, only use your DockerHub account for this value. For example, my-dockerhub-account (without /build-service). Otherwise, you will encounter an error similar to: <code>Error: invalid credentials, ensure registry credentials for 'index.docker.io/my-dockerhub-account/build-service/tanzu-buildpacks_go' are available locally</code> * `REGISTRY-USERNAME` is the username you use to access the registry. `gcr.io` expects `_json_key` as the username when using JSON key file authentication. * `REGISTRY-PASSWORD` is the password you use to access the registry. Note: [Secrets in Tanzu Build Service](secrets-in-tbs.html) for more information about how the registry username and password are used in Tanzu Build Service. #### <a id='offline-additional-config'></a> Additional Configuration Other optional parameters can be added using the `-v` flag: * `admin_users` is a comma separated list of users who will be granted admin privileges on Build Service. * `admin_groups`: a comma separated list of groups that will be granted admin privileges on Build Service. ## <a id='verify-installation'></a> Verify Installation Verify your Build Service installation by first targeting the cluster Build Service has been installed on. To verify your Build Service installation: 1. Download the `kp` binary from the [Tanzu Build Service](https://network.pivotal.io/products/build-service/) page on Tanzu Network. 1. List the cluster builders available in your installation: ``` kp clusterbuilder list ``` You should see an output that looks as follows: ``` NAME READY STACK IMAGE base true io.buildpacks.stacks.bionic <image@sha256:digest> default true io.buildpacks.stacks.bionic <image@sha256:digest> full true io.buildpacks.stacks.bionic <image@sha256:digest> tiny true io.paketo.stacks.tiny <image@sha256:digest> ``` ## <a id='update-deps'></a> Updating Build Service Dependencies Use the following documentation to keep applications patched and up-to-date with Tanzu Build Service: To keep dependencies up-to-date, see [Updating Build Service Dependencies](updating-deps.html) To manage Stacks, see [Managing Stacks](managing-stacks.html) To manage Buildpack Stores, see [Managing Stores](managing-stores.html) ## <a id='access-to-cluster-builders'></a> Ensuring Access to Cluster Builders In order to use Cluster Builders, such as the ones installed with Tanzu Build Service, we suggest to install Tanzu Build Service to a repository that is accessible by the nodes in the kubernetes cluster without credentials. If this is not desired, see [Using Synced Secrets to access Cluster Builders](secrets-in-tbs.html#sync-secrets). ## <a id='ensure-readable-run-image'></a> Ensuring the Run Image is Readable Build Service relies on the run-image being publicly readable or readable with the registry credentials configured in a project/namespace for the builds to be executed successfully. The location of the run image can be identified by running the following command: ``` kp clusterstack status <stack-name> ``` If the cluster stack run image is not public, you may need to create a registry secret in any namespace where Images or Builds will be used. For more details on secrets in Tanzu Build Service, see [Managing Secrets](managing-secrets.html) This can be done with the `kp` CLI: ``` kp secret create my-registry-creds --registry example-registry.io --registry-user my-registry-user --namespace build-namespace ``` ## <a id='next-steps'></a> Next Steps Visit the <a href="managing-images.html">Managing Images and Builds</a> page to learn how to create and manage a new image. ## <a id='install-rbac'></a> Kubernetes Permissions for Installation The minimum Kubernetes RBAC permissions required to install Tanzu Build Service are as follows. This includes the namespaces required for the Kubernetes Roles: ```yaml --- apiVersion: v1 kind: Namespace metadata: name: build-service --- apiVersion: v1 kind: Namespace metadata: name: kpack --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: build-service-install-cluster-role rules: - apiGroups: - "admissionregistration.k8s.io" resources: - mutatingwebhookconfigurations - validatingwebhookconfigurations verbs: - '*' - apiGroups: - "rbac.authorization.k8s.io" resources: - clusterroles - clusterrolebindings verbs: - '*' - apiGroups: - "apiextensions.k8s.io" resources: - customresourcedefinitions verbs: - '*' - apiGroups: - "storage.k8s.io" resources: - storageclasses verbs: - get - list - watch - apiGroups: - kpack.io resources: - builds - builds/status - builds/finalizers - images - images/status - images/finalizers - builders - builders/status - clusterbuilders - clusterbuilders/status - clusterstores - clusterstores/status - clusterstacks - clusterstacks/status - sourceresolvers - sourceresolvers/status verbs: - '*' - apiGroups: - "projects.vmware.com" resources: - projects verbs: - '*' --- apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: build-service-install-role namespace: build-service rules: - apiGroups: - "" resources: - configmaps - secrets - serviceaccounts - services - namespaces verbs: - '*' - apiGroups: - "rbac.authorization.k8s.io" resources: - roles - rolebindings verbs: - '*' - apiGroups: - apps resources: - deployments - daemonsets verbs: - '*' --- apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: kpack-install-role namespace: kpack rules: - apiGroups: - "" resources: - services - serviceaccounts - namespaces - secrets - configmaps verbs: - '*' - apiGroups: - "rbac.authorization.k8s.io" resources: - roles - rolebindings verbs: - '*' - apiGroups: - apps resources: - deployments - daemonsets verbs: - '*' ``` The `kapp` command used to install Tanzu Build Service requires access to ConfigMaps in the namespace that will be used to run `kapp`: ```yaml apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: kapp-role namespace: <my-kapp-namespace> rules: - apiGroups: - "" resources: - configmaps verbs: - '*' ``` Where the namespace `<my-kapp-namespace>` must be the namespace of the Kubernetes context that `kapp` will be run in.