This topic explains how to deploy Contour into a Tanzu Kubernetes (workload) cluster in Tanzu Kubernetes Grid. The procedures below apply to vSphere, Amazon EC2, and Azure deployments.

Ingress Control

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 Tanzu Kubernetes (workload) clusters to provide ingress control services in those clusters.

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

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

Prerequisites

IMPORTANT:

  • In this release of Tanzu Kubernetes Grid, the provided implementation of Contour and Envoy assumes that you use self-signed certificates. To configure Contour and Envoy with your own certificates, engage with VMware Tanzu support.
  • Support for IPv6 addresses in Tanzu Kubernetes Grid is limited; see Deploy Clusters on IPv6 (vSphere Only). If you are not deploying to an IPv6-only networking environment, you must provide IPv4 addresses in the following steps.

Prepare the Workload Cluster for Contour Deployment

To prepare the cluster:

  1. 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.

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

    kubectl config use-context my-cluster-admin@my-cluster
    
  3. If you have not already done so, install Cert Manager in the cluster. For instructions, see Installing Cert Manager.

  4. 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.

  1. Create a configuration file named contour-data-values.yaml for your Contour configuration containing the following:

    vSphere, installing Contour in a workload cluster with NSX Advanced Load Balancer (ALB):

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

    vSphere, installing Contour in the shared services cluster or in a workload cluster without NSX ALB:

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

    Amazon EC2:

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

    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: {}
       nodePorts:
         http: null
         https: null
       externalTrafficPolicy: Cluster
       disableWait: false
     hostPorts:
       enable: true
       http: 80
       https: 443
     hostNetwork: false
     terminationGracePeriodSeconds: 300
     logLevel: info
     pspNames: null
    certificates:
     duration: 8760h
     renewBefore: 360h
    

    This file configures the Contour package.

  2. (Optional) Modify the contour-data-values.yaml file if needed. The Optional Configuration section documents the values that you can customize in the contour-data-values.yaml file and how they can be used to modify the default behavior of Contour in your target cluster. 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 CLI Reference for User-Managed Packages.

    For example:

    tanzu package available get contour.tanzu.vmware.com/1.17.1+vmware.1-tkg.1 --values-schema
    
  3. 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:

      • If the target namespace exists in the cluster, run:

        tanzu package install contour \
        --package-name 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 and deploy the Contour package app, which is managed by kapp-controller. For example, my-packages. If this flag is not specified, the Tanzu CLI uses the default namespace. The Contour and Envoy pods and any other resources associated with Contour and Envoy are created in the tanzu-system-ingress namespace; do not install the Contour package into this namespace.

      • AVAILABLE-PACKAGE-VERSION is the version that you retrieved above.

        For example:

        tanzu package install contour \
        --package-name contour.tanzu.vmware.com \
        --version 1.17.1+vmware.1-tkg.1 \
        --values-file contour-data-values.yaml \
        --namespace my-packages
        
      • If the target namespace does not exist in the cluster, run:

        tanzu package install contour \
        --package-name contour.tanzu.vmware.com \
        --version AVAILABLE-PACKAGE-VERSION \
        --values-file contour-data-values.yaml \
        --namespace TARGET-NAMESPACE \
        --create-namespace
        

        Where:

        • TARGET-NAMESPACE is the namespace in which you want to install the Contour package and deploy the Contour package app, which is managed by kapp-controller. For example, my-packages. If this flag is not specified, the Tanzu CLI uses the default namespace. The Contour and Envoy pods and any other resources associated with Contour and Envoy are created in the tanzu-system-ingress namespace; do not install the Contour package into this namespace.
        • AVAILABLE-PACKAGE-VERSION is the version that you retrieved above.

        For example:

        tanzu package install contour \
        --package-name contour.tanzu.vmware.com \
        --version 1.17.1+vmware.1-tkg.1 \
        --values-file contour-data-values.yaml \
        --namespace my-packages \
        --create-namespace
        

      Alternatively, you can create the namespace before installing the package by running the kubectl create namespace TARGET-NAMESPACE command.

  4. 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.1.0+vmware.1-tkg.2              Reconcile succeeded  my-packages
      contour         contour.tanzu.vmware.com         1.17.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:         1.17.1+vmware.1-tkg.1
    STATUS:                  Reconcile succeeded
    CONDITIONS:              [{ReconcileSucceeded True  }]
    USEFUL-ERROR-MESSAGE:
    
  5. 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
    
  6. Confirm that Contour and Envoy 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
    [...]
    
  7. If you deployed Contour to Amazon EC2 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 Amazon EC2, 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 view data about your deployments.

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

  1. Obtain the name of the Envoy pod:

    ENVOY_POD=$(kubectl -n tanzu-system-ingress get pod -l app=envoy -o name | head -1)
    
  2. Forward the Envoy pod to port 9001 on your local machine:

    kubectl -n tanzu-system-ingress port-forward $ENVOY_POD 9001
    
  3. In a browser, navigate to http://127.0.0.1:9001/.

    You should see the Envoy administration interface.

    Envoy administration interface

  4. Click the links in the Envoy administration interface to see information about the operations in your cluster.

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).

  1. Obtain the name of a Contour pod:

    CONTOUR_POD=$(kubectl -n tanzu-system-ingress get pod -l app=contour -o name | head -1)
    
  2. Forward port 6060 on the Contour pod:

    kubectl -n tanzu-system-ingress port-forward $CONTOUR_POD 6060
    
  3. 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
    
  4. Open contour-dag.png to view the graph.

    Contour DAG file

Optional Configuration

You can further customize your configuration by editing the default values in the Contour package configuration file.

The table below contains information about the values that you can customize in the contour-data-values.yaml file and how they can be used to modify the default behavior of Contour when deployed into a workload cluster.

If you reconfigure your Contour settings after the initial deployment, you must follow the steps in Update a Running Contour Deployment to apply the new configuration to the cluster.

Config Default Description
infrastructure_provider vsphere The underlying infrastructure provider. Valid values are vsphere, aws, and azure.
namespace tanzu-system-ingress The namespace in which to deploy Contour and Envoy.
contour.configFileContents none The YAML contents of the Contour config file. For more information, see Configuration File in the Contour documentation.
contour.replicas 2 How many Contour pod replicas to have.
contour.useProxyProtocol false Whether to enable PROXY protocol for all Envoy listeners.
contour.logLevel info The Contour log level. Valid values are info and debug.
contour.pspNames vmware-system-restricted A comma-separated list of pod security policies (PSPs) to apply to the Contour pods.
envoy.service.type none The type of Kubernetes service to provision for Envoy. Valid values are LoadBalancer, NodePort, and ClusterIP. If not specified, a NodePort service will be used for vsphere and a LoadBalancer for all other infrastructure providers.
envoy.service.externalTrafficPolicy Local The external traffic policy for the Envoy service. Valid values are Local and Cluster.
envoy.service.annotations none Annotations to set on the Envoy service.
envoy.service.nodePorts.http none If envoy.service.type == NodePort, the node port number to expose Envoy's HTTP listener on. If not specified, a node port will be auto-assigned by Kubernetes.
envoy.service.nodePorts.https none If envoy.service.type == NodePort, the node port number to expose Envoy's HTTPS listener on. If not specified, a node port will be auto-assigned by Kubernetes.
envoy.service.aws.LBType classic If infrastructure_provider == aws, the type of AWS load balancer to use. Valid values are classic and nlb. If not using aws, this value is ignored.
envoy.hostPorts.enable false Whether to enable host ports for the Envoy pods. If false, envoy.hostPorts.http and envoy.hostPorts.https are ignored.
envoy.hostPorts.http 80 If envoy.hostPorts.enable == true, the host port number to expose Envoy's HTTP listener on.
envoy.hostPorts.https 443 If envoy.hostPorts.enable == true, the host port number to expose Envoy's HTTPS listener on.
envoy.hostNetwork false Whether to enable host networking for the Envoy pods.
envoy.terminationGracePeriodSeconds 300 The termination grace period, in seconds, for the Envoy pods.
envoy.logLevel info The Envoy log level. Valid values are trace, debug, info, warn, error, critical, and off.
envoy.pspNames none A comma-separated list of pod security policies (PSPs) to apply to the Envoy pods.
certificates.duration 8760h How long the certificates for securing communication between Contour and Envoy should be valid for.
certificates.renewBefore 360h How long before expiration the certificates for securing communication between Contour and Envoy should be renewed.

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:

  1. 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.

  2. 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 1.17.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 CLI Reference for User-Managed Packages. You can use this command to update the version or the configuration of an installed package.

check-circle-line exclamation-circle-line close-line
Scroll to top icon