SAS Viya 2021.1.3 TLS Changes

[#1]

The release of SAS Viya 2021.1.3 makes breaking changes in the way that Transport Layer Security (TLS) is configured. These changes will also impact the next LTS release SAS Viya 2021.2. You will need to understand these changes to be able to successfully deploy SAS Viya 2021.1.3 (and later). Otherwise your site.yaml will not build. In this blog we will examine the changes and provide some details on what each piece is doing.

For the discussions in this blog we will look at four different scenarios. Two scenarios for Full-Stack TLS and two scenarios for Front-Door TLS. With Full-Stack TLS all network traffic will be encrypted as illustrated here: 

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

While Front-Door TLS only uses TLS on connections to the entrance points to the environment, which are NGINX Ingress controller, SAS Cloud Analytic Services controller, and SAS/CONNECT. A high-level view of the connections via the NGINX Ingress controller is illustrated here:

The changes introduced with SAS Viya 2021.1.3 do not make it either easier or harder to configure Full-Stack TLS or Front-Door TLS. The changed content does make it possible for SAS Viya to support other Ingress controllers in future releases.

New Setup for the kustomization.yaml

For the deployment of SAS Viya 2021.1.3 (and later) these changes essentially mean that you need to have different content in your kustomization.yaml. Let’s look at some common scenarios and detail the content you will require. The README.md file located in sas-bases/examples/security/ has additional details.

Full-Stack TLS: Ingress Certificate provided by customer

In this scenario TLS is enabled on all connections and the customer is providing a server identity certificate and associated private key for the NGINX Ingress controller. The kustomization.yaml must include the following TLS related entries:

resources:
  - sas-bases/base
  - sas-bases/overlays/cert-manager-issuer
  - sas-bases/overlays/network/ingress

components:
  - sas-bases/components/security/core/base/full-stack-tls
  - sas-bases/components/security/network/networking.k8s.io/ingress/nginx.ingress.kubernetes.io/full-stack-tls

transformers:
  - sas-bases/overlays/required/transformers.yaml

generators:
  - site-config/security/customer-provided-ingress-certificate.yaml
  - site-config/security/customer-provided-ca-certificates.yaml

There will be other entries in the kustomization.yaml appropriate for the other configuration of your environment.

Full-Stack TLS: Ingress Certificate provided by Cert-Manager

In this scenario TLS is enabled on all connections and cert-manager is used to provide the server identity certificate and associated private key for the NGINX Ingress controller. The kustomization.yaml must include the following TLS related entries:

resources:
  - sas-bases/base
  - sas-bases/overlays/cert-manager-issuer
  - sas-bases/overlays/network/ingress

components:
  - sas-bases/components/security/core/base/full-stack-tls
  - sas-bases/components/security/network/networking.k8s.io/ingress/nginx.ingress.kubernetes.io/full-stack-tls

transformers:
  - sas-bases/overlays/required/transformers.yaml
  - site-config/security/cert-manager-provided-ingress-certificate.yaml

generators:
  - site-config/security/customer-provided-ca-certificates.yaml # This generator is optional.  Include it only if you need to add additional CA Certificates

There will be other entries in the kustomization.yaml appropriate for the other configurable components of your environment.

Front-Door TLS: Ingress Certificate provided by customer

In this scenario TLS is enabled only on the front-door connections (the NGINX Ingress controller, SAS Cloud Analytic Services, and SAS/CONNECT). TLS is not enabled all the services within the environment. The customer provides the server identity certificate and associated private key for the NGINX Ingress controller. The kustomization.yaml must include the following TLS related entries:

resources:
  - sas-bases/base
  - sas-bases/overlays/cert-manager-issuer
  - sas-bases/overlays/network/ingress

components:
  - sas-bases/components/security/core/base/front-door-tls
  - sas-bases/components/security/network/networking.k8s.io/ingress/nginx.ingress.kubernetes.io/front-door-tls

transformers:
  - sas-bases/overlays/required/transformers.yaml

generators:
  - site-config/security/customer-provided-ingress-certificate.yaml
  - site-config/security/customer-provided-ca-certificates.yaml

There will be other entries in the kustomization.yaml appropriate for the other configuration of your environment.

Front-Door TLS: Ingress Certificate provided by Cert-Manager

In this scenario TLS is enabled only on the front-door connections (the NGINX Ingress controller, SAS Cloud Analytic Services, and SAS/CONNECT). TLS is not enabled all the services within the environment. The customer choses to use cert-manager to provide the server identity certificate and associated private key for the NGINX Ingress controller. The kustomization.yaml must include the following TLS related entries:

resources:
  - sas-bases/base
  - sas-bases/overlays/cert-manager-issuer
  - sas-bases/overlays/network/ingress

components:
  - sas-bases/components/security/core/base/front-door-tls
  - sas-bases/components/security/network/networking.k8s.io/ingress/nginx.ingress.kubernetes.io/front-door-tls

transformers:
  - sas-bases/overlays/required/transformers.yaml
  - site-config/security/cert-manager-provided-ingress-certificate.yaml

generators:
  - site-config/security/customer-provided-ca-certificates.yaml # This generator is optional.  Include it only if you need to add additional CA Certificates

There will be other entries in the kustomization.yaml appropriate for the other configuration of your environment.

Description of the different parts of the kustomization.yaml

Now that we have shown the different parts to include in your kustomization.yaml for the different scenarios we will examine what they do.

The first entry common to all scenarios is "sas-bases/overlays/cert-manager-issuer" added under resources. As we’ve discussed before this defines the following:

1. A cert-manager self-signing issuer called sas-viya-selfsigning-issuer.
2. Use the sas-viya-selfsigning-issuer to create a root CA certificate pair (private key and signed certificate) valid for 5 years and stored in the Kubernetes secret called sas-viya-ca-certificate-secret.
3. A cert-manager CA issuer called sas-viya-issuer, that uses the CA created above to sign server identity certificates.

Obviously, the sas-viya-issuer, is required for both Full-Stack scenarios since this issuer will be used to generate the certificate pairs (private key and signed server identity certificate) for all the internal services. However, the sas-viya-issuer is also required for the two Front-Door scenarios as it will generate certificate pairs (private key and signed server identity certificate) for SAS Cloud Analytic Services and SAS/CONNECT.

Next, rather than using transformers, SAS Viya 2021.1.3 (and later) uses the components section to define how the Ingress definitions and individual components and services are updated. For both the Full-Stack scenarios we have:

components:
  - sas-bases/components/security/core/base/full-stack-tls
  - sas-bases/components/security/network/networking.k8s.io/ingress/nginx.ingress.kubernetes.io/full-stack-tls

The entry "sas-bases/components/security/core/base/full-stack-tls" is a directory that contains a separate YAML file for each component in your environment. These YAML files define PatchTransformers that:

1. Add the SAS Certificate Framework init container
2. Add both volumes and volumeMounts for the truststores and certificate pairs (private key and signed server identity certificate)
3. Update the readiness, liveness, and startup probes to use HTTPS
4. Add the required TLS configMap and add the annotation "sas.com/tls-mode=full-stack" to the container
5. Update the service definition to use port 443 and add the annotation "sas.com/tls-mode=full-stack"
6. Update the service and container definitions to set annotations for Prometheus to connect via HTTPS

The entry "sas-bases/components/security/network/networking.k8s.io/ingress/ nginx.ingress.kubernetes.io/full-stack-tls" is also a directory that contains a separate YAML file for each component in your environment. These YAML files define PatchTransformers that:

1. Set an annotation "sas.com/tls-mode=full-stack" and set the service port to 443 for the Ingress definition
2. Add the "/spec/tls" hosts and secretNames to the Ingress definition
3. Add an annotation to the Ingress definition to tell the NGINX Ingress controller the backend protocol is HTTPS

So, you can see for the Full-Stack scenario most of the configuration required for your environment is covered by the YAML files in these two directories.

Whereas, for the two Front-Door scenarios we have:

components:
  - sas-bases/components/security/core/base/front-door-tls
  - sas-bases/components/security/network/networking.k8s.io/ingress/nginx.ingress.kubernetes.io/front-door-tls

The entry "sas-bases/components/security/core/base/front-door-tls" is a directory that contains a separate YAML file for each component in your environment. These YAML files define PatchTransformers that:

1. Add the SAS Certificate Framework init container
2. Add both volumes and volumeMounts for the truststores and certificate pairs (private key and signed server identity certificate)
3. Add the required TLS configMap and add the annotation "sas.com/tls-mode=front-door" to the container

The entry "sas-bases/components/security/network/networking.k8s.io/ingress/ nginx.ingress.kubernetes.io/front-door-tls" is also a directory that contains a separate YAML file for each component in your environment. These YAML files define PatchTransformers that:

1. Set an annotation "sas.com/tls-mode=front-door" for the Ingress definition
2. Add the "/spec/tls" hosts and secretNames to the Ingress definition

This means that for the Front-Door scenarios we still include the SAS Certificate Framework init container even though the individual components and services are not configured for TLS. The SAS Certificate Framework init container is required so that the truststores can be updated to include the certificate trust chain for the NGINX Ingress controller.

The next part of the kustomization.yaml defines how the certificate pair (private key and signed server identity certificate) for the NGINX Ingress controller is provided. Either this is provided by the customer and so we have:

generators:
  - site-config/security/customer-provided-ingress-certificate.yaml

Where the YAML file points to the signed server identity certificate and corresponding private key. Alternatively, if cert-manager will be generating the certificate pair (private key and signed server identity certificate) for the NGINX Ingress controller we have:

transformers:
  - site-config/security/cert-manager-provided-ingress-certificate.yaml

Where this YAML file defines the cert-manager issuer to be used for the NGINX Ingress controller certificate pair (private key and signed server identity certificate).

Finally, in all four scenarios we have presented above we also include:

generators:
  - site-config/security/customer-provided-ca-certificates.yaml # This generator is optional.  Include it only if you need to add additional CA Certificates

As the comment associated with this makes clear this is optional. This enables you to load any other CA certificates into the truststores constructed by the SAS Certificate Framework init container. For example, this could be used to update the truststores for secure LDAP or secure Mail connections.

Conclusion

As we have shown the content you must place in the kustomization.yaml to setup either Front-Door TLS or Full-Stack TLS has changed with SAS Viya 2021.1.3 (and later). If you are manually working through the configuration reading the documentation and README.md you will be following the correct steps. However, if you have deployed some automation to construct the kustomization.yaml this will need to be updated to account for these changes.

The changed content in the kustomization.yaml does not make it either easier or harder to configure Full-Stack TLS or Front-Door TLS. The changed content does make it possible for SAS Viya to support other Ingress controllers in future releases.

Find more articles from SAS Global Enablement and Learning here.