Using pre-configured certificates with NetScaler Kubernetes Gateway Controller
This topic explains how to use certificates or certificate bundles that are already configured on your NetScaler appliance with your Kubernetes Gateway. This feature simplifies certificate management by allowing you to reference existing certificates instead of managing them as Kubernetes Secrets.
Benefits
Some of the benefits of using pre-configured certificates with NetScaler Kubernetes Gateway Controller are as follows:
-
Simplified Management: Use certificates already configured on your NetScaler appliance.
-
No Secret Creation: Avoid the overhead of creating and maintaining Kubernetes Secrets for certificates.
-
Centralized Control: Manage certificates directly on NetScaler while configuring them in Kubernetes.
How to reference pre-configured certificates
When defining your Gateway, you can reference pre-configured certificates or certificate bundles in the certificateRefs section of your listener configuration.
Certificate types
You can reference the following two types of pre-configured certificates or certificate-bundles:
-
Domain Certificate: Server certificates for HTTPS connections.
-
CA Certificate: Certificate Authority certificates for client authentication. You can specify multiple CA certificates.
Basic configuration
Here’s a simple example of referencing a pre-configured certificate:
NetScaler setup
add ssl certkey my-default-cert -cert /nsconfig/ssl/server.crt -key /nsconfig/ssl/server.key
<!--NeedCopy-->
add ssl certkeybundle my-cert-bundle -bundlefile /nsconfig/ssl/bundle.pem
<!--NeedCopy-->
Or use a pre-configured certificate bundle:
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: my-gateway-with-preconf-certs
namespace: default
spec:
gatewayClassName: my-gateway-class
addresses:
- type: IPAddress
value: "<IP ADDRESS>"
listeners:
- name: https-listener
protocol: HTTPS
port: 443
tls:
mode: Terminate
certificateRefs:
- group: "netscaler.certkeybundle"
kind: "default" # Only one domain cert. Should be bound as default unless kind is specified.
name: "my-cert-bundle" # <---- Name of ssl certkeybundle configured on netscaler
<!--NeedCopy-->
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: my-gateway-with-preconf-certs
namespace: default
spec:
gatewayClassName: my-gateway-class
addresses:
- type: IPAddress
value: "<IP ADDRESS>"
listeners:
- name: https-listener
protocol: HTTPS
port: 443
tls:
mode: Terminate
certificateRefs:
- group: "netscaler.certkey"
kind: "default" # Only one domain cert. Should be bound as default unless kind is specified.
name: "my-default-cert" # <---- Name of ssl certkey configured on netscaler
<!--NeedCopy-->
The description of the configuration fields are as follows:
-
group: Specify the certificate source:- “netscaler.certkey” for pre-configured NetScaler certificates
- “netscaler.certkeybundle” for pre-configured NetScaler certificate bundles
-
kind: Specify the certificate type:- “ca” - Use for Certificate Authority certificates (for client authentication). You can specify multiple CA certificates
- “sni” - Use for server certificates that should be bound as SNI.
Note:
kindis optional for server certificates. If only one server certificate is present without kind, it will be bound as default. If multiple server certificates are present, they will automatically be bound as SNI certificates -
name: The name of the certificate as configured on your NetScaler appliance
Common Scenarios
Scenario 1: Single certificate
Use a single pre-configured certificate for your HTTPS listener:
listeners:
- name: https
protocol: HTTPS
port: 443
tls:
mode: Terminate
certificateRefs:
- group: "netscaler.certkey"
name: "company-ssl-cert"
<!--NeedCopy-->
Scenario 2: Multiple domains certificates
When multiple server certificates are provided, you must create an SSL profile with snienable set to ENABLED:
listeners:
- name: https
protocol: HTTPS
port: 443
tls:
mode: Terminate
certificateRefs:
- group: "netscaler.certkey"
name: "primary-domain-cert"
- group: "netscaler.certkey"
name: "secondary-domain-cert"
<!--NeedCopy-->
Required SSL profile
apiVersion: citrix.com/v1
kind: sslprofile
metadata:
name: frontend-ssl-custom
spec:
targetRef:
- name: my-gateway-https
sectionName: https
config:
sslprofiletype: "frontend"
snienable: "ENABLED"
<!--NeedCopy-->
Scenario 3: Client authentication with CA certificate
Add CA certificates for client authentication:
listeners:
- name: https
protocol: HTTPS
port: 443
tls:
mode: Terminate
certificateRefs:
- group: "netscaler.certkey"
kind: "default"
name: "server-cert"
- group: "netscaler.certkey"
kind: "ca"
name: "client-ca-cert"
<!--NeedCopy-->
Scenario 4: Using certificate bundles
If you have certificate bundles configured on NetScaler, use the netscaler.certkeybundle group:
listeners:
- name: https
protocol: HTTPS
port: 443
tls:
mode: Terminate
certificateRefs:
- group: "netscaler.certkeybundle"
name: "my-cert-bundle"
<!--NeedCopy-->
Scenario 5: Combining pre-configured and Kubernetes certificates
You can combine pre-configured certificates with regular Kubernetes secrets:
listeners:
- name: https
protocol: HTTPS
port: 443
tls:
mode: Terminate
certificateRefs:
- kind: Secret
name: "k8s-tls-secret"
- group: "netscaler.certkey"
name: "additional-domain-cert"
<!--NeedCopy-->
Prerequisites
Before using pre-configured certificates or certificate-bundle in your Gateway:
-
Ensure that the certificates are already configured on your NetScaler appliance.
-
Note the exact certificate names as they appear in NetScaler and refer it in the Gateway CRD.
-
If certificates are created on NetScaler after deploying the Gateway CRD instance, delete and re-apply the Gateway resource YAML to ensure proper binding
Troubleshooting
Some of the common issues and their resolutions are as follows:
-
Issue: Certificate Not Found
Resolution: Ensure that the certificate name exactly matches the name configured on NetScaler.
-
Issue: Wrong Certificate Served
Resolution: When using multiple certificates (SNI), ensure the following:
- An SSL profile with snienable set to ENABLED is created and bound to the SSL virtual server.
- You can create an SSL profile using the SSLProfile CRD - Example SSLProfile configuration that references your Gateway:
apiVersion: citrix.com/v1 kind: sslprofile metadata: name: frontend-ssl-custom spec: targetRef: - name: my-gateway-https sectionName: https config: sslprofiletype: "frontend" snienable: "ENABLED" <!--NeedCopy-->
Summary
Referencing pre-configured certificates in your Kubernetes Gateway is straightforward and can be summarized as follows:
-
Use group: “netscaler.certkey” for regular certificates
-
Use group: “netscaler.certkeybundle” for certificate bundles
-
Specify kind: “ca” for CA certificates. For server certificates, kind is optional
-
Provide the certificate name as configured on NetScaler