Shared Ingress issuer in Tanzu Application Platform

This topic tells you about the Tanzu Application Platform (commonly known as TAP) shared ingress issuer.

The shared ingress issuer is an on-platform representation of a certificate authority. It provides a method to set up TLS for the entire platform. All participating components get their ingress certificates issued by it.

This is the recommended best practice for issuing ingress certificates on Tanzu Application Platform.

The ingress issuer is designated by the single Tanzu Application Platform configuration value shared.ingress_issuer. It refers to a cert-manager.io/v1/ClusterIssuer.

By default, a self-signed issuer is used. It’s called tap-ingress-selfsigned and has limitations. For more information, see Limitations of the default, self-signed issuer.

VMware recommends you replace the default self-signed issuer with your own issuer. For more information, see Replacing the default ingress issuer.

Component-level configuration of TLS takes precedence and can be mixed with the ingress issuer. For more information, see Overriding TLS for components.

You can deactivate the ingress issuer. For more information, see Deactivating TLS for ingress.

Prerequisites

To use the Tanzu Applicatin Platforms ingress issuer your certificate authority must be representable by a cert-manager ClusterIssuer. You need one of the following:

  • Your own CA certificate
  • Your CA is an ACME, Venafi, or Vault-based issuer, for example, LetsEncrypt
  • Your CA can be represented by an external cert-manager ClusterIssuer.

Without one of the above, you cannot use the issuer ingress, but you can still configure TLS for components. For more information, see Ingress certificates inventory.

Default

By default, Tanzu Application Platform installs and uses a self-signed CA as its ingress issuer for all components.

This default ingress issuer is a self-signed cert-manager.io/v1/ClusterIssuer and is provided by Tanzu Application Platform’s cert-manager package. Its default name is tap-ingress-selfsigned.

The default ingress issuer is appropriate for testing and evaluation, but VMware recommends that you replace it with your own issuer.

Important

If cert-manager.tanzu.vmware.com is excluded from the installation, then tap-ingress-selfsigned is not installed either. In this case, bring your own ingress issuer.

Limitations of the default, self-signed issuer

The default ingress issuer represents a self-signed certificate authority. This is not problematic as far as security is concerned, however, it is not included in any trust chain configured.

As a result, nothing trusts the default ingress issuer implicitly, not even Tanzu Application Platform components. While the issued certificates are valid in principal, they are rejected, for example, by your browser. Furthermore, some interactions between components are not functional by default.

Trusting the default, self-signed issuer

You can trust the default ingress issuer by including tap-ingress-selfsigned’s certificate in Tanzu Application Platforms’s trusted CA certificates and your device’s certificate chain.

Caution

This approach is discouraged. Instead, replace the default ingress issuer.

  1. Obtain tap-ingress-selfsigned’s PEM-encoded certificate

    kubectl get secret \
    tap-ingress-selfsigned-root-ca \
    --namespace cert-manager \
    --output go-template='{{ index .data "tls.crt" | base64decode }}'
    
  2. Add the certificate to custom CA certificates by appending it to shared.ca_cert_data and applying the Tanzu Application Platforms installation values file.

  3. Add the certificate to your device’s trust chain. The trust chain will vary depending on your operating system and privileges.

Replacing the default ingress issuer

Tanzu Application Platform’s default ingress issuer can be replaced by any other cert-manager-compliant ClusterIssuer.

To replace the default ingress issuer:

Custom CA
Prerequisites

You need your own CAs certificate and private key for this.

Complete the following steps:

  1. Create your ClusterIssuer

    Create a Secret and ClusterIssuer which represent your CA on the platform:

    ---
    apiVersion: v1
    kind: Secret
    type: kubernetes.io/tls
    metadata:
      name: my-company-ca
      namespace: cert-manager
    stringData:
      tls.crt: #! your CA's PEM-encoded certificate
      tls.key: #! your CA's PEM-encoded private key
    
    ---
    apiVersion: cert-manager.io/v1
    kind: ClusterIssuer
    metadata:
      name: my-company
    spec:
      ca:
        secretName: my-company-ca
    
  2. Set shared.ingress_issuer to the name of your issuer:

    #! my-tap-values.yaml
    #! ...
    shared:
      ingress_issuer: my-company-ca
    #! ...
    
  3. Apply the Tanzu Application Platform installation values file.

    After the configuration is applied, components eventually obtain certificates from the new issuer and will serve them.

LetsEncrypt production

Complete the following steps

Prerequisites
  • Public CAs, like LetsEncrypt, record signed certificates in publicly-available certificate logs for the purpose of certificate transparency. Ensure that you are OK with this before using LetsEncrypt.
  • LetsEncrypt’s production API has rate limits.
  • LetsEncrypt requires your shared.ingress_domain to be accessible from the Internet.
  • Depending on your setup, you might need to adjust .spec.acme.solvers
  • Replace .spec.acme.email with the email which should receive notices for certificates from LetsEncrypt.

Caution ACME HTTP01 challenges can fail under certain conditions. For more information, see ACME challenges.

  1. Create a ClusterIssuer for Let’s Encrypts production API:

    ---
    apiVersion: cert-manager.io/v1
    kind: ClusterIssuer
    metadata:
      name: letsencrypt-production
    spec:
      acme:
        email: certificate-notices@my-company.com
        privateKeySecretRef:
          name: letsencrypt-production
        server: https://acme-v02.api.letsencrypt.org/directory
        solvers:
          - http01:
              ingress:
                class: contour
    
  2. Set shared.ingress_issuer to the name of your issuer:

    #! my-tap-values.yaml
    #! ...
    shared:
      ingress_issuer: letsencrypt-production
    #! ...
    
  3. Apply Tanzu Application Platform installation values file.

    Once the configuration is applied, components eventually obtain certificates from the new issuer and will serve them.

LetsEncrypt staging
Complete the following steps

Prerequisites

  • Public CAs - like LetsEncrypt - record signed certificates in publicly-available certificate logs for the purpose of certificate transparency. Ensure that you are OK with this before using LetsEncrypt.
  • LetsEncrypt’s staging API is not a publicly-trusted CA. You have to add its certificate to your devices trust chain and Tanzu Application Platform’s custom CA certificates.
  • LetsEncrypt requires your shared.ingress_domain to be accessible from the Internet.
  • Depending on your setup you might need to adjust .spec.acme.solvers.
  • Replace .spec.acme.email with the email which should receive notices for certificates from LetsEncrypt.
Caution

ACME HTTP01 challenges can fail under certain conditions. For more information, see ACME challenges.

  1. Create a ClusterIssuer for Let’s Encrypts staging API:

    ---
    apiVersion: cert-manager.io/v1
    kind: ClusterIssuer
    metadata:
      name: letsencrypt-staging
    spec:
      acme:
        email: certificate-notices@my-company.com
        privateKeySecretRef:
          name: letsencrypt-production
        server: https://acme-staging-v02.api.letsencrypt.org/directory
        solvers:
          - http01:
              ingress:
                class: contour
    
  2. Set shared.ingress_issuer to the name of your issuer:

    #! my-tap-values.yaml
    #! ...
    shared:
      ingress_issuer: letsencrypt-staging
    #! ...
    
  3. Apply Tanzu Application Platform installation values file.

    When the configuration is applied, components obtain certificates from the new issuer and serve them.

Other
Complete the following steps:

You can use any other cert-manager-supported ClusterIssuer as an ingress issuer for Tanzu Application Platform.

Cert-manager supports a host of in-tree and out-of-tree issuers. Refer to cert-manager’s documentation of issuers.

  1. Set shared.ingress_issuer to the name of your issuer:

    #! my-tap-values.yaml
    #! ...
    shared:
      ingress_issuer: my-company-ca
    #! ...
    
  2. Apply the Tanzu Application Platform installation values file.

    After the configuration is applied, components obtain certificates from the new issuer and serve them.


There are many ways and tools to assert that new certificates are issued and served. It is best to connect to one of the ingress endpoints and inspect the certificate it serves.

The openssl command-line utility is available on most operating systems. The following command retrieves the certificate from an ingress endpoint and shows its text representation:

# replace tap.example.com with your Tanzu Application Platform installation's ingress domain
openssl s_client -showcerts -servername tap-gui.tap.example.com -connect tap-gui.tap.example.com:443 <<< Q | openssl x509 -text -noout

Alternatively, use a browser to navigate to the ingress endpoint and click the lock icon in the navigation bar to inspect the certificate.

Deactivating TLS for ingress

While VMware does not recommend it, you can deactivate the ingress issuer by setting shared.ingress_issuer: "".

Overriding TLS for components

You can override TLS settings for each component. In your Tanzu Application Platform values file a component’s configuration takes precedence over shared values. For more information about which components have ingress and how to configure them, see components.

Note

The approaches can be mixed. Use a shared ingress issuer, but override TLS configuration for select components.

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