Install Contour in Workload Clusters Deployed by a Standalone Management Cluster

Last Updated February 10, 2025

This topic explains how to deploy Contour into a workload cluster in Tanzu Kubernetes Grid.

This documentation is applicable only to Tanzu Kubernetes Grid with management clusters. If you are using TKGS with vSphere Supervisor, see Installing Standard Packages on TKG Service Clusters.

Contour is a Kubernetes ingress controller that uses the Envoy edge and service proxy. Tanzu Kubernetes Grid includes signed binaries for Contour and Envoy, which you can deploy into workload clusters to provide ingress control services in those clusters.

You deploy Contour and Envoy directly into workload clusters. Deploying Contour is a prerequisite if you want to deploy the Prometheus, Grafana, and Harbor packages.

For general information about ingress control, see Ingress Controllers in the Kubernetes documentation.

Prerequisites

A bootstrap machine with the following installed:
- Tanzu CLI, Tanzu CLI plugins, and kubectl, as described in Install the Tanzu CLI and Kubernetes CLI for Use with Standalone Management Clusters.
- yq v4.5 or later.
You have deployed at least one workload cluster. For instructions, see Creating Workload Clusters.

In this release of Tanzu Kubernetes Grid, the provided implementation of Contour and Envoy assumes that you use self-signed certificates.

Prepare the Workload Cluster for Contour Deployment

To prepare the cluster:

Get the admin credentials of the workload cluster into which you want to deploy Contour. For example:
```
tanzu cluster kubeconfig get my-cluster --admin
```
In the example above, my-cluster is the name of the cluster.

Set the context of kubectl to the cluster. For example:

kubectl config use-context my-cluster-admin@my-cluster

If the cluster does not have a package repository with the Contour package installed, such as the tanzu-standard repository, install one:
```
tanzu package repository add PACKAGE-REPO-NAME --url PACKAGE-REPO-ENDPOINT --namespace tkg-system
```
Where:
- PACKAGE-REPO-NAME is the name of the package repository, such as tanzu-standard or the name of a private image registry configured with ADDITIONAL_IMAGE_REGISTRY variables.
- PACKAGE-REPO-ENDPOINT is the URL of the package repository.
  - For the TKG v2.5.2 release, the tanzu-standard URL is projects.packages.broadcom.com/tkg/packages/standard/repo:v2025.1.27. See List Package Repositories to obtain this value from the Tanzu CLI, or in Tanzu Mission Control see the Addons > Repositories list in the Cluster pane.
If you have not already done so, install cert-manager in the cluster. For instructions, see Install Cert Manager for Certificate Management.
Proceed to Deploy Contour into the Workload Cluster below.

Deploy Contour into the Workload Cluster

After you have set up the cluster, you must first create the configuration file that is used when you install the Contour package and then install the package.

As of v2.5, TKG does not support clusters on AWS or Azure. See the End of Support for TKG Management and Workload Clusters on AWS and Azure in the Tanzu Kubernetes Grid v2.5 Release Notes.

Create a configuration file for the Contour package by retrieving the default configuration of the package:
```
tanzu package available get contour.tanzu.vmware.com/PACKAGE-VERSION --default-values-file-output FILE-PATH
```
Where PACKAGE-VERSION is the version of the Contour package that you want to install and FILE-PATH is the location to which you want to save the configuration file, for example, contour-data-values.yaml.

Configure the following in the contour-data-values.yaml file:

vSphere

This file configures the Contour package on vSphere.

---
infrastructure_provider: vsphere
namespace: tanzu-system-ingress
contour:
 configFileContents: {}
 useProxyProtocol: false
 replicas: 2
 pspNames: "vmware-system-restricted"
 logLevel: info
envoy:
 service:
   type: NodePort
   annotations: {}
   externalTrafficPolicy: Cluster
   disableWait: false
 hostPorts:
   enable: true
   http: 80
   https: 443
 hostNetwork: false
 terminationGracePeriodSeconds: 300
 logLevel: info
certificates:
 duration: 8760h
 renewBefore: 360h

AWS

This file configures the Contour package on AWS.

---
infrastructure_provider: aws
namespace: tanzu-system-ingress
contour:
 configFileContents: {}
 useProxyProtocol: false
 replicas: 2
 pspNames: "vmware-system-restricted"
 logLevel: info
envoy:
 service:
   type: LoadBalancer
   annotations: {}
   externalTrafficPolicy: Cluster
   aws:
     LBType: classic
   disableWait: false
 hostPorts:
   enable: true
   http: 80
   https: 443
 hostNetwork: false
 terminationGracePeriodSeconds: 300
 logLevel: info
certificates:
 duration: 8760h
 renewBefore: 360h

Azure

This file configures the Contour package on Azure.

---
infrastructure_provider: azure
namespace: tanzu-system-ingress
contour:
 configFileContents: {}
 useProxyProtocol: false
 replicas: 2
 pspNames: "vmware-system-restricted"
 logLevel: info
envoy:
 service:
   type: LoadBalancer
   annotations: {}
   externalTrafficPolicy: Cluster
   disableWait: false
 hostPorts:
   enable: true
   http: 80
   https: 443
 hostNetwork: false
 terminationGracePeriodSeconds: 300
 logLevel: info
certificates:
 duration: 8760h
 renewBefore: 360h

TKG v2.5 does not support clusters on AWS or Azure. See the End of Support for TKG Management and Workload Clusters on AWS and Azure in the Tanzu Kubernetes Grid v2.5 Release Notes.

If you are installing Contour to a vSphere cluster that uses NSX ALB as a load balancer service provider, modify the contour-default-values.yaml file to set envoy.service.type to LoadBalancer:
```
[...]
envoy:
 service:
   type: LoadBalancer
```
If you are installing Contour to an internet-restricted AWS environment, modify the contour-data-values.yaml file to add the following annotation to the Envoy service:
```
infrastructure_provider: aws
[...]
envoy:
 service:
   annotations:
     service.beta.kubernetes.io/aws-load-balancer-internal: "true"
```
(Optional) Modify the contour-data-values.yaml file if needed.

See Contour Configuration Parameters for a full list of available parameters.

For example, the Contour package deploys two Contour replicas by default, but the number of replicas is configurable. You set this number in the contour.replicas value in contour-data-values.yaml. In most cases, you do not need to modify the contour-data-values.yaml file.

You can also retrieve these values by running the below command against your target cluster:
```
tanzu package available get contour.tanzu.vmware.com/AVAILABLE-VERSION --values-schema
```
Where AVAILABLE-VERSION is the version of the Contour package. The --values-schema flag retrieves the valuesSchema section from the Package API resource for the Contour package. You can set the output format, --output, for the values schema to yaml, json, or table. For more information, see Packages in Install and Manage Packages.

For example:
```
tanzu package available get contour.tanzu.vmware.com/v1.29.1+vmware.1-tkg.1 --values-schema
```
If your contour-data-values.yaml file contains comments, remove them:
```
yq -i eval '... comments=""' contour-data-values.yaml
```
Install the Contour package:
1. Retrieve the name of the available package:
```
tanzu package available list -A
```
2. Retrieve the version of the available package:
```
tanzu package available list contour.tanzu.vmware.com -A
```
3. Install the package:
```
tanzu package install contour \
--package contour.tanzu.vmware.com \
--version AVAILABLE-PACKAGE-VERSION \
--values-file contour-data-values.yaml \
--namespace TARGET-NAMESPACE
```
  Where:
  - TARGET-NAMESPACE is the namespace in which you want to install the Contour package. For example, the my-packages or tanzu-cli-managed-packages namespace.
    - If the --namespace flag is not specified, the Tanzu CLI uses the default namespace. The Contour and Envoy pods and any other resources associated with the Contour component are created in the tanzu-system-ingress namespace; do not install the Contour package into this namespace.
    - The specified namespace must already exist, for example from running kubectl create namespace my-packages.
  - AVAILABLE-PACKAGE-VERSION is the version that you retrieved above.
  For example:
```
tanzu package install contour \
--package contour.tanzu.vmware.com \
--version v1.29.1+vmware.1-tkg.1 \
--values-file contour-data-values.yaml \
--namespace my-packages
```

Confirm that the contour package has been installed:

tanzu package installed list -A

For example:

tanzu package installed list -A
- Retrieving installed packages...
  NAME            PACKAGE-NAME                     PACKAGE-VERSION                   STATUS               NAMESPACE
  cert-manager    cert-manager.tanzu.vmware.com    1.12.2+vmware.1-tkg.1              Reconcile succeeded  my-packages
  contour         contour.tanzu.vmware.com         v1.29.1+vmware.1-tkg.1             Reconcile succeeded  my-packages
  antrea          antrea.tanzu.vmware.com                                            Reconcile succeeded  tkg-system
  [...]

To see more details about the package, you can also run:

tanzu package installed get contour --namespace PACKAGE-NAMESPACE

Where PACKAGE-NAMESPACE is the namespace in which the contour package is installed.

For example:

tanzu package installed get contour --namespace my-packages
\ Retrieving installation details for contour...
NAME:                    contour
PACKAGE-NAME:            contour.tanzu.vmware.com
PACKAGE-VERSION:         v1.29.1+vmware.1-tkg.1
STATUS:                  Reconcile succeeded
CONDITIONS:              [{ReconcileSucceeded True  }]
USEFUL-ERROR-MESSAGE:

Confirm that the contour app has been successfully reconciled in your PACKAGE-NAMESPACE:

kubectl get apps -A

For example:

NAMESPACE     NAME             DESCRIPTION           SINCE-DEPLOY   AGE
my-packages   cert-manager     Reconcile succeeded   78s            3h5m
my-packages   contour          Reconcile succeeded   57s            6m3s
tkg-system    antrea           Reconcile succeeded   45s            3h18m
[...]

If the status is not Reconcile Succeeded, view the full status details of the contour app. Viewing the full status can help you troubleshoot the problem.

kubectl get app contour --namespace PACKAGE-NAMESPACE -o yaml

Where PACKAGE-NAMESPACE is the namespace in which you installed the package. If troubleshooting does not help you solve the problem, you must uninstall the package before installing it again:

tanzu package installed delete contour --namespace PACKAGE-NAMESPACE

Confirm that Contour and Envoy pods are running in the tanzu-system-ingress namespace:

kubectl get pods -A

For example:

kubectl get pods -A
NAMESPACE              NAME                                                        READY   STATUS    RESTARTS   AGE
[...]
tanzu-system-ingress   contour-5dc6fc667c-c4w8k                                    1/1     Running   0          14m
tanzu-system-ingress   contour-5dc6fc667c-jnqwn                                    1/1     Running   0          14m
tanzu-system-ingress   envoy-mgfll                                                 2/2     Running   0          14m
[...]

If you deployed Contour to AWS or Azure, confirm that a load balancer has been created for the Envoy service:
```
kubectl get svc envoy -n tanzu-system-ingress -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'
```
On AWS, the loadbalancer has a name similar to aabaaad4dfc8e4a808a70a7cbf7d9249-1201421080.us-west-2.elb.amazonaws.com. On Azure, it will be an IP address similar to 20.54.226.44.

Access the Envoy Administration Interface Remotely

After you have deployed Contour into a cluster, you can use the embedded Envoy administration interface to retrieve data about your deployments.

For information about the Envoy administration interface, see Administration Interface in the Envoy documentation.

Obtain the name of the Envoy pod:

ENVOY_POD=$(kubectl -n tanzu-system-ingress get pod -l app=envoy -o name | head -1)

Forward the Envoy pod to port 9001 on your bootstrap machine:

kubectl -n tanzu-system-ingress port-forward $ENVOY_POD 9001

From your bootstrap machine, retrieve information from your Contour deployment by sending curl queries to the Envoy administration endpoints listed in Accessing the Envoy Administration Interface. For example, use the /config_dump endpoint to retrieve the currently loaded configuration:
```
curl http://localhost:9001/config_dump
```

Visualize the Internal Contour Directed Acyclic Graph (DAG)

When you have started running workloads in your cluster, you can visualize the traffic information that Contour exposes in the form of a directed acyclic graph (DAG).

Install Graphviz if it is not already installed. This package provides the dot command that creates the DAG image file.

Obtain the name of a Contour pod:

CONTOUR_POD=$(kubectl -n tanzu-system-ingress get pod -l app=contour -o name | head -1)

Forward port 6060 on the Contour pod:

kubectl -n tanzu-system-ingress port-forward $CONTOUR_POD 6060

Open a new terminal window and download and save the DAG as a *.png file. The below command requires you to install dot on your system if it is not present already.
```
curl localhost:6060/debug/dag | dot -T png > contour-dag.png
```
Open contour-dag.png to view the graph.

Update a Running Contour Deployment

If you need to make changes to the configuration of the Contour package after deployment, follow the steps below to update your deployed Contour package:

Update the Contour configuration in the contour-data-values.yaml file. For example, you can change the number of Contour replicas by setting contour.replicas to a new value.

See Contour Configuration Parameters for a full list of available parameters.
Update the installed package:
```
tanzu package installed update contour \
--version INSTALLED-PACKAGE-VERSION \
--values-file contour-data-values.yaml \
--namespace INSTALLED-PACKAGE-NAMESPACE
```
Where:
- INSTALLED-PACKAGE-VERSION is the version of the installed Contour package.
- INSTALLED-PACKAGE-NAMESPACE is the namespace in which the Contour package is installed.
For example:
```
tanzu package installed update contour \
--version v1.29.1+vmware.1-tkg.1 \
--values-file contour-data-values.yaml \
--namespace my-packages
```
The Contour package will be reconciled using the new value or values that you added. It can take up to five minutes for kapp-controller to apply the changes.

For more information about the tanzu package installed update command, see Update a Package in Install and Manage Packages. You can use this command to update the version or the configuration of an installed package.

Content feedback and comments

Tanzu Packages latest

Install Contour in Workload Clusters Deployed by a Standalone Management Cluster

Prerequisites

Prepare the Workload Cluster for Contour Deployment

Deploy Contour into the Workload Cluster

Access the Envoy Administration Interface Remotely

Visualize the Internal Contour Directed Acyclic Graph (DAG)

Update a Running Contour Deployment