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. Learn about its prerequisites.
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 that 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.
To use the Tanzu Application Platform ingress issuer, your certificate authority must be representable by a cert-manager ClusterIssuer
. In particular, you need one of the following:
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.
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.
ImportantIf
cert-manager.tanzu.vmware.com
is excluded from the installation, thentap-ingress-selfsigned
is not installed either. In this case, bring your own ingress 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.
You can trust the default ingress issuer by including tap-ingress-selfsigned
’s certificate in the Tanzu Application Platform trusted CA certificates and your device’s certificate chain.
CautionThis approach is discouraged. Instead, replace the default ingress issuer.
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 }}'
Add the certificate to custom CA certificates by appending it to shared.ca_cert_data
and applying Tanzu Application Platform’s installation values
Add the certificate to your device’s trust chain. The trust chain will vary depending on your operating system and privileges.
Tanzu Application Platform’s default ingress issuer can be replaced by any other cert-manager-compliant ClusterIssuer.
To replace the default ingress issuer:
Prerequisites
You need your own CA certificates and private key for this.
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
Set shared.ingress_issuer
to the name of your issuer:
#! my-tap-values.yaml
#! ...
shared:
ingress_issuer: my-company-ca
#! ...
Apply the Tanzu Application Platform installation values file.
When the configuration is applied, components obtain certificates from the new issuer and serve them.
Prerequisites
shared.ingress_domain
to be accessible from the Internet..spec.acme.email
with the email which should receive notices for certificates from LetsEncrypt.CautionACME HTTP01 challenges can fail under certain conditions. For more information, see ACME challenges.
Create a ClusterIssuer
for Let’s Encrypts production API:
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-production
spec:
acme:
email: [email protected]
privateKeySecretRef:
name: letsencrypt-production
server: https://acme-v02.api.letsencrypt.org/directory
solvers:
- http01:
ingress:
class: contour
Set shared.ingress_issuer
to the name of your issuer
#! my-tap-values.yaml
#! ...
shared:
ingress_issuer: letsencrypt-production
#! ...
Apply Tanzu Application Platform installation values
When the configuration is applied, components obtain certificates from the new issuer and serve them.
Prerequisites
shared.ingress_domain
to be accessible from the Internet..spec.acme.email
with the email which should receive notices for certificates from LetsEncrypt.CautionACME HTTP01 challenges can fail under certain conditions. For more information, see ACME challenges.
Create a ClusterIssuer
for Let’s Encrypts staging API:
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-staging
spec:
acme:
email: [email protected]
privateKeySecretRef:
name: letsencrypt-production
server: https://acme-staging-v02.api.letsencrypt.org/directory
solvers:
- http01:
ingress:
class: contour
Set shared.ingress_issuer
to the name of your issuer
#! my-tap-values.yaml
#! ...
shared:
ingress_issuer: letsencrypt-staging
#! ...
Apply Tanzu Application Platform installation values
After the configuration is applied, components obtain certificates from the new issuer and serve them.
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. See cert-manager’s documentation of issuers.
Set shared.ingress_issuer
to the name of your issuer
#! my-tap-values.yaml
#! ...
shared:
ingress_issuer: my-company-ca
#! ...
Apply Tanzu Application Platform’s installation values
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.
While VMware does not recommend it, you can deactivate the ingress issuer by setting shared.ingress_issuer: ""
.
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
NoteThe approaches can be mixed. Use a shared ingress issuer, but override TLS configuration for select components.