installing-tas-for-kubernetes.html.md.erb

---
title: Installing Tanzu Application Service for Kubernetes
owner: Tanzu Application Service Release Engineering
---
<% current_page.data.title = "Installing #{vars.app_runtime_full}" %>

This topic describes how to install <%= vars.app_runtime_full %> (<%= vars.app_runtime_short %>)
from the VMware Tanzu Network and from a relocated image in a private container image registry.

## <a id='overview'></a> Overview

To configure installation settings and install <%= vars.app_runtime_short %>:

1. [Prepare the Installation](#prepare-installation)
1. [Generate Internal Configuration Values](#generate-configuration-values)
1. [Install <%= vars.app_runtime_short %>](#install-tas-for-k8s)

## <a id='prerequisites'></a> Prerequisites

Before you install <%= vars.app_runtime_short %>, you must:

+ Configure all of the required or recommended installation resources.
See [Configuring Installation Values](configuring-installation-values.html).
+ Configure Apps Manager. See [Configuring Apps Manager](configuring-apps-manager.html).
+ Install Cloud Foundry Command Line Interface (cf CLI) v7.0.1 or later.
See [Upgrading to cf CLI v7](https://docs.pivotal.io/application-service/2-10/cf-cli/v7.html).

## <a id='support-backup'></a> Prepare the Installation

To prepare for installing <%= vars.app_runtime_short %>:

1. Verify that your root directory contains `configuration-values` and `tanzu-application-service` directories.
1. Change directory to the `tanzu-application-service` directory.
1. To enable support for backing up and restoring <%= vars.app_runtime_short %>, copy the
`disaster-recovery.yml` file from the `config-optional` directory to the `config` directory:

    ```
    cp config-optional/disaster-recovery.yml config/disaster-recovery.yml
    ```

## <a id='generate-configuration-values'></a> Generate Internal Configuration Values

<%= vars.app_runtime_short %> requires internal configuration values, credentials and certificates to coordinate its components. These configuration values, credentials and certificates must be supplied to the <%= vars.app_runtime_short %> installation script.

To generate the internal values, credentials and certificates needed during <%= vars.app_runtime_short %> installation, use a helper script in the installation resources:

1. Change directory to the `tanzu-application-service` directory.
1. To create new configuration files, run:

    ```bash
    ./bin/generate-values.sh CONFIG-VALUES-PATH
    ```
<br>
    Where `CONFIG-VALUES-PATH` is the path to the `configuration-values` directory.
    For example, `../configuration-values`.
<br>
    The `generate-values` script creates:
    * **_generated-values.yml**: The `_generated-values.yml` file contains generated configuration values
    that will be read during installation.
    The default location for the `_generated-values.yml` file is: `../configuration-values/_generated-values.yml`.
 <br>
    * **tas-vars**: The `tas-vars` data store contains credentials and certificates
    that are not used during <%= vars.app_runtime_short %> installation but may be needed for future value generation.
    The default location for the `tas-vars` data store is: `../configuration-values/vars-store/tas-vars`.
<br>
    * **Certificates**: Self-signed `system-certificate` and `workload-certificate` certificates are created
    if you did not provide these certificates when completing the steps in [Configuring Installation Values](configuring-installation-values.html).


<p class="note">Ensure all of the generated files in the <code>configuration-values</code> directory are stored securely.
    These files contain important installation secrets and should be preserved
    for future installations.
</p>

<p class= "note warning">
  <strong>Warning:</strong> Do not rotate encryption keys in the Kubernetes stack in this version of <%= vars.app_runtime_short %>. 
  The <code>capi.database.encryption_key</code> value should not be modified after it is initially set because
  the Cloud API fails during <code>cf push</code> for Kubernetes clusters with a modified encryption key. 
</p>

<p class= "note warning">
  <strong>Warning:</strong> Do not rotate the blobstore secret key in this version of <%= vars.app_runtime_short %>. 
  The <code>blobstore.secret_access_key</code> value should not be altered after it is initially set because
  redeployments fail when using configurations with a modified blobstore secret key. 
</p>

## <a id='install-tas-for-k8s'></a> Install <%= vars.app_runtime_short %>

To install <%= vars.app_runtime_short %>:

1. Follow the procedure appropriate for the configuration you created:
    * [Install <%= vars.app_runtime_short %> from the VMware Tanzu Network](#install-tas-for-k8s-from-network)
    * [Install <%= vars.app_runtime_short %> from a Private System Registry](#post-image-relocation)

1. [Configure DNS for the <%= vars.app_runtime_short %> Ingress Gateway](#post-installation-networking-configuration)
1. [Validate Your <%= vars.app_runtime_short %> Installation](installing-tas-for-kubernetes.html#post-installation-configuration)

### <a id='install-tas-for-k8s-from-network'></a> Install <%= vars.app_runtime_short %> from the VMware Tanzu Network

To install <%= vars.app_runtime_short %> from the VMware Tanzu Network:

1. To validate your configuration:

    ```bash
    kubectl cluster-info
    ```
    Inspect the output. Ensure that your Kubernetes client configuration targets the intended cluster for installation.

1. Change directory into the `tanzu-application-service` directory.

1. To create a cluster configurations file:

    ```bash
    ./bin/cluster-detect.sh > ../configuration-values/cluster-values.yml
    ```

    The `cluster-detect` script communicates with the kube API to determine deployment values
    and saves those values in a `cluster-values` configuration file.

1. To install <%= vars.app_runtime_short %>, run the installation script:

    ```bash
    ./bin/install-tas.sh ../configuration-values
    ```

    The command installs <%= vars.app_runtime_short %> using the deployment values you generated previously.

### <a id='post-image-relocation'></a> Install <%= vars.app_runtime_short %> from a Private System Registry

After uploading your <%= vars.app_runtime_short %> images to the private registry,
you can install <%= vars.app_runtime_short %> using a modified installation procedure.

To install <%= vars.app_runtime_short %>:

1. To validate your configuration:

    ```bash
    kubectl cluster-info
    ```
    Inspect the output. Ensure that your Kubernetes client configuration targets the intended cluster for installation.

1. Change directory into the `tanzu-application-service` directory.

1. To create a cluster configurations file:

    ```bash
    ./bin/cluster-detect.sh > ../configuration-values/cluster-values.yml
    ```

    The `cluster-detect` script communicates with the kube API to determine deployment values
    and saves those values in a `cluster-values` configuration file.

1. To deploy <%= vars.app_runtime_short %> using the images in the private registry:


    ```
    ytt -f config \
          -f ../configuration-values | \
          kbld -f- -f relocated_images.yml > /tmp/final_deployment.yml
    kapp deploy -a cf -f /tmp/final_deployment.yml
    ```

## <a id='post-installation-networking-configuration'></a> Configure DNS for the <%= vars.app_runtime_short %> Ingress Gateway

To configure DNS entries for the <%= vars.app_runtime_short %> ingress gateway:

* If you intend to use a Kubernetes `LoadBalancer` service for the ingress gateway, 
create and configure a Kubernetes `LoadBalancer` service:  
    1. [Configure the Load Balancer]
    (configuring-installation-values.html#configure-lb)  
    1. [Configure the Ingress Gateway DNS With a Kubernetes Load Balancer]
    (#post-installation-dns-with-k8s-lb)
<br>
* If you do not intend to use a Kubernetes `LoadBalancer` service for the ingress gateway, 
configure DNS without the `LoadBalancer` service:  
    * If you are using an external load balancer for the ingress gateway:  
    [Configure the Ingress Gateway DNS With an External Load Balancer](#post-installation-dns-with-lb)  
<br>
    * If you are not using an external load balancer for the ingress gateway:  
    [Configure the Ingress Gateway DNS Without a Load Balancer](#post-installation-dns-no-lb)



### <a id='post-installation-dns-with-k8s-lb'></a> Configure the Ingress Gateway DNS With a Kubernetes Load Balancer

This section describes how to configure DNS if you have configured <%= vars.app_runtime_short %> to
use a Kubernetes LoadBalancer Service for the ingress gateway.

To configure DNS with your system domain resolving to the external IP address of the load balancer:

1. To retrieve the value of the external IP address or hostname assigned to the Istio ingress gateway service:

    ```
    kubectl -n istio-system get service istio-ingressgateway -ojsonpath='{.status.loadBalancer.ingress[0].ip}'
    kubectl -n istio-system get service istio-ingressgateway -ojsonpath='{.status.loadBalancer.ingress[0].hostname}'
    ```
    For example:
    <pre class="terminal">
    $ kubectl -n istio-system get service istio-ingressgateway -ojsonpath='{.status.loadBalancer.ingress[0].ip}'
    10.193.105.162
    $ kubectl -n istio-system get service istio-ingressgateway -ojsonpath='{.status.loadBalancer.ingress[0].hostname}'
    ae7b1093f9c3b44fd9982b828b32ccad-2445920965.us-west-2.elb.amazonaws.com
    </pre>

1. In your DNS zone, create an entry for your system domain:
    * If you have an external IP address, create a wildcard `A` record for the system domain,
        resolving to the external IP address:

        ```
        *.SYSTEM-DOMAIN
        ```
        Where `SYSTEM-DOMAIN` is the system domain.
    <br>
    * If you have a hostname, create a wildcard CNAME record for the system domain,
        resolving to the hostname:

        ```
        *.SYSTEM-DOMAIN
        ```
        Where `SYSTEM-DOMAIN` is the system domain.

    Ensure you include the `*.` wildcard prefix in the new record so that all subdomains of the system domain also resolve to the load balancer.

For information about configuring <%= vars.app_runtime_short %> to
use a Kubernetes LoadBalancer Service for the ingress gateway, see
[Use a LoadBalancer Service for the Ingress Gateway](configuring-installation-values.html#adjust-installation-resources-networking),


### <a id='post-installation-dns-with-lb'></a> Configure the Ingress Gateway DNS With an External Load Balancer

This section describes how to configure DNS
if you have an external load balancer to use for ingress to the <%= vars.app_runtime_short %> installation and
have deployed <%= vars.app_runtime_short %> without a Kubernetes LoadBalancer service
for the ingress gateway.

To configure the external load balancer to forward HTTP and HTTPS traffic to the Kubernetes worker nodes:

1. To retrieve the list of existing worker nodes with their internal IP addresses:

    ```
    kubectl get nodes --output='wide'
    ```
    For example:
    <pre class="terminal">
    $ kubectl get nodes --output='wide'
NAME                                   STATUS   ROLES    AGE     VERSION   INTERNAL-IP    EXTERNAL-IP
5e329c31-f1d7-4548-936b-3a58d4b166d3   Ready    \<none>   5h49m   v1.15.5   10.85.87.133   10.85.87.133
a6ad3f07-787c-4d90-b8e1-032be34e9d7f   Ready    \<none>   5h43m   v1.15.5   10.85.87.134   10.85.87.134
a8eb78a2-e3b4-4d8a-8c32-67bf0e13c0bf   Ready    \<none>   5h43m   v1.15.5   10.85.87.135   10.85.87.135
af7dc8da-a7b0-4cf2-a940-c9248168e609   Ready    \<none>   5h43m   v1.15.5   10.85.87.136   10.85.87.136
cc6ef11f-e253-4553-9cb0-bebc7d958f64   Ready    \<none>   5h42m   v1.15.5   10.85.87.137   10.85.87.137
    </pre>

1. Configure your external load balancer to forward traffic on TCP ports `80` and `443` to the set of
internal IP addresses for the Kubernetes worker nodes.

1. Configure DNS records in your DNS zone:
    * If your load balancer has a static IP, create a wildcard `A` record for the system domain,
        resolving to the external IP address of the load balancer:

        ```
        *.SYSTEM-DOMAIN
        ```
        Where `SYSTEM-DOMAIN` is the system domain.
<br>
    * If your load balancer has a DNS name instead of static IP, such as an AWS load balancer,
        create a wildcard `CNAME` record for the system domain,
        resolving to the external IP address of the load balancer:

        ```
        *.SYSTEM-DOMAIN
        ```
        Where `SYSTEM-DOMAIN` is the system domain.


    Ensure you include the `*.` wildcard prefix in the new record
    so that all subdomains of the system domain also resolve to this IP address.

### <a id='post-installation-dns-no-lb'></a> Configure the Ingress Gateway DNS Without a Load Balancer

This section describes how to configure your DNS
if you do not have an external load balancer to use for ingress and
have deployed <%= vars.app_runtime_short %> without a Kubernetes LoadBalancer service
for the ingress gateway.

To set up your DNS records to establish ingress connectivity directly to the worker nodes:

1. To retrieve the list of existing worker nodes with their external IP addresses:

    ```
    kubectl get node --selector='!node-role.kubernetes.io/master' -o wide
    ```
    For example:
    <pre class="terminal">
    $ kubectl get node --selector='!node-role.kubernetes.io/master' -o wide
NAME                                   STATUS   ROLES    AGE     VERSION   INTERNAL-IP    EXTERNAL-IP
5e329c31-f1d7-4548-936b-3a58d4b166d3   Ready    \<none>   5h49m   v1.15.5   10.85.87.133   10.85.87.133
a6ad3f07-787c-4d90-b8e1-032be34e9d7f   Ready    \<none>   5h43m   v1.15.5   10.85.87.134   10.85.87.134
a8eb78a2-e3b4-4d8a-8c32-67bf0e13c0bf   Ready    \<none>   5h43m   v1.15.5   10.85.87.135   10.85.87.135
af7dc8da-a7b0-4cf2-a940-c9248168e609   Ready    \<none>   5h43m   v1.15.5   10.85.87.136   10.85.87.136
cc6ef11f-e253-4553-9cb0-bebc7d958f64   Ready    \<none>   5h42m   v1.15.5   10.85.87.137   10.85.87.137
</pre>

1. Create a wildcard `A` record for the system domain in your DNS zone,
resolving to the set of external IP addresses for the worker nodes:

    ```
    *.SYSTEM-DOMAIN
    ```
    Where `SYSTEM-DOMAIN` is the system domain. Include the `*.` wildcard prefix so that all subdomains
    of the system domain also resolve to the IP addresses.


## <a id='post-installation-configuration'></a> Validate Your <%= vars.app_runtime_short %> Installation

<p class="note"><strong>Note</strong>: Managing apps and services on <%= vars.app_runtime_short %> requires cf CLI v7.0.1 or later.</p>

To validate your <%= vars.app_runtime_short %> installation:

1. Use cf CLI to target the installation at the `api` subdomain of the system domain:

    ```
    cf api api.SYSTEM-DOMAIN --skip-ssl-validation
    ```

    Where `SYSTEM-DOMAIN` is your <%= vars.app_runtime_short %> installation system domain.
1. Change directory into the directory containing the `tanzu-application-service` and `configuration-values`
directories.

1. To set the `CF_ADMIN_PASSWORD` environment variable to the CF administrative password
stored in the `cf_admin_password` key in the `configuration-values/_generated-values.yml` file:

    ```
    CF_ADMIN_PASSWORD="$(bosh interpolate configuration-values/_generated-values.yml \
            --path /cf_admin_password)"
    ```

1. Log into the installation as the admin user:

    ```
    cf auth admin "$CF_ADMIN_PASSWORD"
    ```

1. Create and target an organization and space for the verification application.

    For example:
    <pre class="terminal">$ cf create-org test-org
    $ cf create-space -o test-org test-space
    $ cf target -o test-org -s test-space
    </pre>

1. To clone the Cloud Foundry test application from GitHub to your workstation:

    ```
    git clone https://github.com/cloudfoundry-samples/test-app.git
    ```

    For more information see [Cloud Foundry test application](https://github.com/cloudfoundry-samples/test-app)
    on GitHub.

1. Change directory into the resulting `test-app` directory.


1. To push the test app to your <%= vars.app_runtime_short %> installation:

    ```
    cf push test-app --hostname test-app
    ```

1. To validate the test app is running, make a request to the app after the `cf push` command succeeds:

    ```
    curl test-app.APPS-DOMAIN
    ```

    Where `APPS-DOMAIN` is your <%= vars.app_runtime_short %> installation apps domain.

    <p class="note">
      <strong>Note:</strong> The route for the test application defaults to a subdomain of the system domain.
    </p>

To validate Velero installation:

1. Use kubectl to confirm the back up and restore components have been installed successfully:

    ```
    kubectl get pods -n cf-system -l app=cf-metadata
    ```


## <a id='check-installed-version'></a> Check the Version of <%= vars.app_runtime_short %> on a Cluster

To check the version of <%= vars.app_runtime_short %> currently installed on a cluster, use `kubectl`:

```
kubectl get ConfigMap version -n tas-system -o jsonpath="{.data}"
```

This command produces output in the following format:

```
map[commit:__GIT_COMMIT__ version:__BUILD_NUMBER__]
```

For example:
<pre class="terminal">
map[commit:53ad0edd093dbad71debc193541b5c6f0b2b094d version:0.4.0-build.57]
</pre>

## <a id="next"></a> Next Steps

After you complete this procedure, proceed to
[Configuring Back Up and Restore for <%= vars.app_runtime_full %>](bandr-configuration.html).