Install, link, and update certificates on a NetScaler using the NetScaler Ingress Controller
On the Ingress NetScaler, you can install, link, and update certificates. Many server certificates are signed by multiple hierarchical certificate authorities (CAs). This means that certificates form a chain.
A certificate chain is an ordered list of certificates containing an SSL certificate and certificate authority (CA) certificates. It enables the receiver to verify that the sender and all CAs are trustworthy. The chain or path begins with the SSL certificate, and each certificate in the chain is signed by the entity identified by the next certificate in the chain.
Any certificate that sits between the SSL certificate and the root certificate is called a chain or intermediate certificate. The intermediate certificate is the signer or issuer of the SSL certificate. The root CA certificate is the signer or issuer of the intermediate certificate.
If the intermediate certificate is not installed on the server (where the SSL certificate is installed) it may prevent some browsers, mobile devices, and applications from trusting the SSL certificate. To make the SSL certificate compatible with all clients, it is necessary that the intermediate certificate is installed.
Certificates linking in Kubernetes
The NetScaler Ingress Controller supports automatic provisioning and renewal of TLS certificates using the Kubernetes cert-manager. The cert-manager issues certificates from different sources, such as Let’s Encrypt and HashiCorp Vault and converts them to Kubernetes secrets.
The following diagram explains how the cert-manager performs certificate management.
When you create a Kubernetes secret from a PEM certificate embedded with multiple CA certificates, you need to link the server certificates with the associated CAs. While applying the Kubernetes secret, you can link the server certificates with all the associated CAs using the Ingress NetScaler. Linking the server certificates and CAs enable the receiver to verify if the sender and CAs are trustworthy.
The following is a sample Ingress definition:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: frontendssl
spec:
rules:
- host: frontend.com
http:
paths:
- backend:
service:
name: frontend
port:
number: 443
path: /web-frontend/frontend.php
pathType: Prefix
tls:
- secretName: certchain1
<!--NeedCopy-->
On the NetScaler, you can verify if certificates are added to the NetScaler. Perform the following:
-
Log on to the NetScaler command-line interface.
-
Verify if certificates are added to the NetScaler using the following command:
>show certkeyFor sample outputs, see the NetScaler documentation.
-
Verify that the server certificate and CAs are linked using the following command:
>show certlinkOutput:
1) Cert Name: k8s-3KC24EQYHG6ZKEDAY5Y3SG26MT2 CA Cert Name: k8s-3KC24EQYHG6ZKEDAY5Y3SG2_ic1 2) Cert Name: k8s-3KC24EQYHG6ZKEDAY5Y3SG2_ic1 CA Cert Name: k8s-3KC24EQYHG6ZKEDAY5Y3SG2_ic2
Certificate key bundle in NetScaler® by using the NetScaler Ingress Controller
NetScaler Ingress Controller now supports certificate bundle (certkeybundle) functionality, which is supported on NetScaler starting from release 14.1 build 21.x. With this functionality, the issue with the certificate chain and the additional handling that is required when two certificates share an intermediate CA are resolved. For more information on certificate key bundle support in NetScaler, see Support for SSL certificate key bundle.
NetScaler Ingress Controller creates a certificate bundle for certificates provided in:
- The TLS section of Ingress
-
service.citrix.com/secretannotation inserviceTypeLB - Secret in the Listener
To enable this feature, a new environment variable CERT_BUNDLE is added in the NetScaler Ingress Controller, which can be set by using the certBundle argument from the Helm Charts. For more information on setting the certBundle, see Helm Charts of NetScaler Ingress Controller. NetScaler Ingress Controller adds the certificate bundle to the content switching virtual server of type SSL.
Certificate Bundle creation in NetScaler does not work in the following scenarios:
- A secure back end (service group of type SSL) is configured.
- Self-signed certificates are present.
-
preconfigured-certkeyannotation is set in the ingress, or servicetypeLB, or Listener.
Points to note
-
Certificate bundle creation in NetScaler fails if the following order is not met:
-
Server certificate (SC) must be placed at the top of the bundle file.
-
IC[1-9] are intermediate certificates. IC[i] is issued by IC[i+1]. The certificates must be placed in a sequence, and all the intermediate certificates must be present in the bundle.
-
Certificates must be of PEM format only.
-
Server certificate key (SCK) can be placed anywhere in the bundle.
-
A maximum of 9 intermediate certificates are supported
-
-
If you upgrade the Controllers with the
CERT_BUNDLEfeature, the previous certificate key bindings get removed and a newcertkeybundlegets created. The newcertkeybundlegets bound to the context switching virtual server of type SSL.
SSL CA certificate Bundle support with NetScaler Ingress Controller
Starting from release 14.1 build 29.x, NetScaler supports CA certificate bundle binding to an SSL virtual server, service, and service group. With this support, you can bind CA certificate bundle without creating separate files for each CA certificate. NetScaler Ingress Controller supports the SSL CA certificate bundle binding to virtual server and service group based on Ingress or serviceTypeLB.
The customer can create the Kubernetes secret for the CA Cert bundle and can provide the Kubernetes secret in the ingress and serviceTypeLB using the annotation.
Kubectl create secret generic tls-ca --from-file=tls.crt=rootCA.crt
<!--NeedCopy-->
In the preceding example, rootCA.crt contains the CA certificate chain.
Notes:
Bundle creation fails if the following order is not met:
IC[1-9]are intermediate certificates.IC[i]is issued byIC[i+1]. The certificates must be placed in a sequence, all the intermediate certificates must be present in the bundle, and the root certificate must be the last one. In the following example, the certificate set (bundle.pem) contains the following files:
- First intermediate certificate (bundle_ic1)
- Second intermediate certificate (bundle_ic2)
- Root certificate
- A maximum of 9 intermediate certificates are supported.
- The certificate must be in PEM format.
- If a CA certificate key pair is bound to a virtual server, service or service group then you cannot bind the CA certificate bundle and conversely.
- Encrypted private keys are not supported.
- DTLS bind and Cluster are not supported.
- OCSP and CRL are not supported.
To bind the provided Kubernetes secret in NetScaler as CA certificate bundle, set the cacertbundle argument as true in the annotation.
For ingress
ingress.citrix.com/ca-secret: '{"frontend-hotdrinks": {"ca-name": "abcca", "cacertbundle": "true"}, "coffee-beverage": {"ca-name": "abc1ca", "cacertbundle": "true"}}'
<!--NeedCopy-->
ingress.citrix.com/backend-ca-secret: '{"frontend-hotdrinks": {"ca-name": "abcca", "cacertbundle": "true"}, "coffee-beverage": {"ca-name": "abc1ca", "cacertbundle": "true"}}'
<!--NeedCopy-->
In the preceding example, frontend-hotdrinks and coffee-beverage are the name of the backend service in the ingress and abcca and abc1ca are the Kubernetes Secret created for CA certificate chain.
For ServiceTypeLB
service.citrix.com/ca-secret: '{"https-443":{"ca-name" : "abc1ca", "cacertbundle": "true"}}'
<!--NeedCopy-->
service.citrix.com/backend-ca-secret: '{"https-443":{"ca-name" : "abc1ca", "cacertbundle": "true"}}'
<!--NeedCopy-->
In the preceding example, https-443 is the port-protocol combination of the service and abc1ca is two Kubernetes Secret created for the CA certificate chain.
Preconfigured CA Certificate bundle in the NetScaler
For ingress
ingress.citrix.com/preconfigured-certkey: '{"certs": [ {"name": "ca3bun", "type": "ca"}]}'
<!--NeedCopy-->
ingress.citrix.com/preconfigured-backend-ca-certkey: '{"frontend-hotdrinks": "ca3bun", "coffee-beverage": "ca3bun"}'
<!--NeedCopy-->
For ServiceTypeLB
service.citrix.com/preconfigured-backend-ca-certkey: '{"443-tcp": "ca3bun", "https-6443" :"ca3bun"}'
<!--NeedCopy-->
service.citrix.com/preconfigured-ca-certkey: '{"443-tcp": ["ca3bun", "ca4bun"], "https-6443": "ca3bun"}'
<!--NeedCopy-->
In the preceding example, ca3bun and the ca4bun are the CA Certificate bundle created in NetScaler.
Support for preconfigured certificate bundle created in NetScaler through NetScaler Ingress Controller
Starting from NetScaler Ingress Controller release 3.1.34, certificate bundle configuration is supported for the Kubernetes Secret created for the certificate chain. The customer can now create a certkey bundle for the certificate chain in the NetScaler and same can be provided in the Ingress or serviceTypeLB.
For ingress
ingress.citrix.com/preconfigured-certkey: '{"certs": [{"name": "abc4cert", "type": "default"}]}'
<!--NeedCopy-->
ingress.citrix.com/preconfigured-backend-certkey: '{"frontend-hotdrinks": "abc4cert", "coffee-beverage": "abc4cert"}'
<!--NeedCopy-->
In the preceding example, abc4cert is the certificate bundle created in the NetScaler for a certificate chain and frontend-hotdrinks and coffee-beverage are the backend service names mentioned in the ingress.
For serviceTypeLB
service.citrix.com/preconfigured-backend-certkey: '{"443-tcp":"abc3cert","https-6443": "abc4cert"}'
<!--NeedCopy-->
service.citrix.com/preconfigured-certkey: '{"443-tcp": " abc3cert ", "https-6443": "abc4cert "}'
<!--NeedCopy-->
In the preceding example, 443-tcp and https-6443 are port-protocol combinations provided in the serviceType LB and abc3cert and abc4cert are two certificate chain created in the NetScaler using the certkey bundle.