Product Documentation
NetScaler ingress controller
View PDF

TLS certificates handling in NetScaler Ingress Controller

April 11, 2024
Contributed by: 
C C

NetScaler Ingress Controller provides option to configure TLS certificates for NetScaler SSL-based virtual servers. The SSL virtual server intercepts SSL traffic, decrypts it and processes it before sending it to services that are bound to the virtual server.

By default, SSL virtual server can bind to one default certificate and the application receives the traffic based on the policy bound to the certificate. However, you have the Server Name Indication (SNI) option to bind multiple certificates to a single virtual server. NetScaler determines which certificate to present to the client based on the domain name in the TLS handshake.

NetScaler Ingress Controller handles the certificates in the following three ways:

Prerequisite

For handling TLS certificates using NetScaler Ingress Controller, you need to enable TLS support in NetScaler for the application and also if you are using certificates in your Kubernetes deployment then you need to generate Kubernetes secret using the certificate.

Enable TLS support in NetScaler for the application

NetScaler Ingress Controller uses the TLS section in the ingress definition as an enabler for TLS support with NetScaler.

Note:

If there is a default certificate or if there are preconfigured certificates, you need to add an empty secret in the spec.tls.secretname field in your ingress definition to enable TLS.

The following sample snippet of the ingress definition:

spec:
  tls:
  - secretName:
<!--NeedCopy-->

Generate Kubernetes secret

To generate Kubernetes secret for an existing certificate, use the following kubectl command:

     kubectl create secret tls k8s-secret --cert=path/to/tls.cert --key=path/to/tls.key  --namespace=default

    secret “k8s-secret” created

The command creates a Kubernetes secret with a PEM formatted certificate under tls.crt key and a PEM formatted private key under tls.key key.

Alternatively, you can also generate the Kubernetes secret using the following YAML definition:

apiVersion: v1
kind: Secret
metadata:
  name: k8s-secret
data:
  tls.crt: base64 encoded cert
  tls.key: base64 encoded key
<!--NeedCopy-->

Deploy the YAML using the kubectl -create <file-name> command. It creates a Kubernetes secret with a PEM formatted certificate under tls.crt key and a PEM formatted private key under tls.key key.

NetScaler Ingress Controller default certificate

The default secrets provided in NetScaler Ingress Controller can be used to configure SSL and SSL SNI certificates in NetScaler. You can use default-sni-certificate and default-ssl-sni-certificate arguments to provide a secret to configure non-SNI and SNI certificates respectively. When you specify the arguments in the NetScaler Ingress Controller deployment YAML file, provide the secret name and the namespace where the secret has been deployed in the cluster as following:

  • Argument to add in the YAML file to use the default certificate as a non-SNI certificate: --default-ssl-certificate <NAMESPACE>/<SECRET_NAME>.

  • Argument to add in the YAML file to use the default certificate as an SNI certificate: --default-ssl-sni-certificate <NAMESPACE>/<SECRET_NAME>

Note:

If you deploy NetScaler Ingress Controller using a Helm chart or operators, both the default secrets must be deployed in the same namespace where NetScaler Ingress Controller is being deployed. Provide the non-SNI secret name in the defaultSSLCertSecret parameter and the SNI secret name in the defaultSSLSNICertSecret parameter during the NetScaler Ingress Controller installation. For example, defaultSSLCertSecret: <non-SNI secret name>; defaultSSLSNICertSecret: <SNI secret name>.

The following is a sample NetScaler Ingress Controller YAML definition file that contains a TLS secret (hotdrink.secret) picked from the ssl namespace and provided as the NetScaler Ingress Controller default certificate.

Note:

Namespace is mandatory along with a valid SECRET_NAME.

apiVersion: v1
kind: Pod
metadata:
  name: cic
  labels:
    app: cic
spec:
  serviceAccountName: cpx
  containers:
  - name: cic
    image: "xxxx"
    imagePullPolicy: Always
    args:
    - --default-ssl-certificate
      ssl/hotdrink.secret
    env:
    # Set NetScaler ADM Management IP
    - name: "NS_IP"
      value: "xx.xx.xx.xx"
    # Set port for Nitro
    - name: "NS_PORT"
      value: "xx"
    # Set Protocol for Nitro
    - name: "NS_PROTOCOL"
      value: "HTTP"
    # Set username for Nitro
    - name: "NS_USER"
      value: "nsroot"
    # Set user password for Nitro
    - name: "NS_PASSWORD"
      value: "nsroot"
<!--NeedCopy-->

For information about the behaviour of NetScaler Ingress Controller in different scenarios related to Kubernetes ingress in Kubernetes cluster, see the following table.

Default SSL Secret in NetScaler Ingress Controller Default SSL SNI Secret in NetScaler Ingress Controller Host in Ingress Secret in Ingress Actions
Yes No Not provided Not provided Bind non-SNI secret as a non-SNI certificate in SSL virtual server.
No Yes Not provided Not Provided Bind default SNI secret as an SNI certificate in SSL virtual server.
Yes

Yes

Not Provided

Not provided

  • Bind non-SNI secret as a non-SNI certificate.
  • Bind SNI secret as an SNI certificate.
  • Also, bind non-SNI secret as SNI since multiple secrets are getting bound.
Yes No Provided Not provided Bind non-SNI secret as a non-SNI certificate in SSL virtual server.
No Yes Provided Not provided Bind SNI secret as an SNI certificate in SSL virtual server.
Yes

Yes

Provided

Not provided

  • Bind non-SNI secret as a non-SNI certificate in SSL virtual server.
  • Bind SNI secret as an SNI certificate in SSL virtual server.
  • Also, bind non-SNI secret as an SNI certificate since multiple secrets are getting bound.
Anything Anything Not provided Provided Bind secret provided as a non-SNI certificate in SSL virtual server.
Anything Anything Provided Provided Bind secret provided as an SNI certificate in SSL virtual server.
Anything Anything Provided/Not provided Multiple Bind all the secrets provided as SNI certificates in SSL virtual server.

For information about behaviour of NetScaler Ingress Controller in different scenarios related to OpenShift route in OpenShift cluster, see the following table.

Default SSL Secret in NetScaler Ingress Controller Default SSL SNI Secret in NetScaler Ingress Controller Route type Key and Cert in Route Actions
Yes No Edge Not Provided Bind non-SNI secret as a non-SNI certificate in SSL virtual server.
No Yes Edge Not Provided Bind default SNI secret as an SNI certificate in SSL virtual server.
Yes

Yes

Edge

Not Provided

  • Bind non-SNI secret as a non-SNI certificate.
  • Bind SNI secret as an SNI certificate.
  • Also, bind non-SNI secret as SNI because multiple secrets are getting bound in SSL virtual server.
Yes No Reencrypt Not Provided Bind non-SNI secret as a non-SNI certificate in SSL virtual server.
No Yes Reencrypt Not provided Bind SNI secret as a SNI certificate in SSL virtual server.
Yes

Yes

Reencrypt

Not provided

  • Bind non-SNI secret as a non-SNI certificate in SSL virtual server.
  • Bind SNI secret as an SNI certificate.
  • Also, bind non-SNI secret as SNI since multiple secrets are getting bound in SSL virtual server.
Yes No Passthrough Not provided Bind non-SNI secret as an SNI certificate.
No Yes Passthrough Not provided Bind SNI secret as an SNI certificate in SSL virtual server.
Yes
Yes
Passthrough
Not provided
  • Bind non-SNI secret as an SNI certificate in SSL virtual server.
  • Bind SNI secret as an SNI certificate in SSL virtual server.
Anything Anything Edge Provided Bind secret provided as an SNI certificate in SSL virtual server.
Anything Anything Reencrypt Provided Bind secret provided as an SNI certificate in SSL virtual server.
Anything Anything Passthrough OpenShift doesn’t allow NA

Preconfigured certificates

NetScaler Ingress Controller allows you to use the certkeys that are already configured on the NetScaler. You must provide the details about the certificate using the following annotation in your ingress definition:

    ingress.citrix.com/preconfigured-certkey : '{\"certs\": \[ {\"name\": \"<name>\", \"type\": \"default|sni|ca\"} ] }'

You can provide details about multiple certificates as a list within the annotation. Also, you can define the way the certificate is treated. In the following sample annotation, certkey1 is used as a non-SNI certificate and certkey2 is used as an SNI certificate:

    ingress.citrix.com/preconfigured-certkey : '{"certs": [ {"name": "certkey1", "type": "default"}, {"name": "certkey2", "type": "sni"} ] }’

If the type parameter is not provided with the name of a certificate, then it is considered as the default (non-SNI) type.

Note:

Ensure that you use this feature in cases where you want to reuse the certificates that are present on the NetScaler and bind them to the applications that are managed by NetScaler Ingress Controller. NetScaler Ingress Controller does not manage the life cycle of the certificates. That is, it does not create or delete the certificates, but only binds them to the necessary applications.

TLS section in the ingress YAML

Kubernetes allows you to provide the TLS secrets in the spec: section of an ingress definition. This section describes how the NetScaler Ingress Controller uses these secrets.

With the host section

If the secret name is provided with the host section, NetScaler Ingress Controller binds the secret as an SNI certificate.

spec:
  tls:
  - secretName: fruitjuice.secret
    hosts:
    - items.fruit.juice
<!--NeedCopy-->

Without the host section

If the secret name is provided without the host section, NetScaler Ingress Controller binds the secret as a default certificate.

spec:
  tls:
  - secretName: colddrink.secret
<!--NeedCopy-->

Note:

If there are more than one secret given then NetScaler Ingress Controller binds all the certificates as SNI enabled certificates.

Points to note

  1. When, multiple secrets are provided to the NetScaler Ingress Controller, the following precedence is followed:

    1. preconfigured-default-certkey or non-host tls secret
    2. default-ssl-certificate

  2. If there is a conflict in precedence among the same grade certificates (for example, two ingress files configure a non-host TLS secret each, as default/non-SNI type), then the NetScaler Ingress Controller binds the NetScaler Ingress Controller default certificate as the non-SNI certificate and uses all other certificates with SNI.

  3. Certificate used for a secret given under the TLS section must have a CN name. Otherwise, it does not bind to NetScaler.

  4. If SNI enabled for SSL virtual server then:

    • Non-SNI (Default) certificate is used for the following HTTPs requests:

       curl -1 -v -k https://1.1.1.1/

 curl -1 -v -k -H 'HOST:*.colddrink.beverages' https://1.1.1.1/

    • SNI enabled certificate is used for a request with full domain name:

       curl -1 -v -k https://items.colddrink.beverages/

      If any request is received that does not match with certificates, CN name fails.

TLS certificates handling in NetScaler Ingress Controller
April 11, 2024
Contributed by: 
C C
April 11, 2024
Contributed by: 
C C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.