Requirements

In order to configure TLS for Ambassador routes, the following items are required:

• Hostname
• (Optional) TLS Certificate
• (Optional) Private Key
• (Optional) Intermediate Certificate

Configuration Steps

With the items specified above, follow the steps listed below to configure TLS:

1. Set hostname in values file

In the first step, specify the hostname in the values.*.yaml file of your project.

Example: Configuration for "example.com" as hostname for external ambassador route for production deployment looks like the following. The hostname needs to be specified in values.*.hostspace.yaml file, e.g. values.hostspace.yaml.

...
ambassador:
  internal:
    enabled: true
    prefix: /
    domain:
    hostname:
  external:
    enabled: true
    prefix: /
    domain:
    hostname: example.com
...

2. (Optional) Create and Upload a values file with TLS certificate and Private key

Starting with version 3.7 of the CloudOne platform, a default TLS certificate and private key will be configured into the Ambassador mapping by the platform. This certificate and private key combination can be superceded by a custom pair as an option.

In order to configure a custom TLS certificate and private key for an ambassador route, create a values file with the TLS certificate and private key and upload it as a Secure File.

Example: Continuing the above example with "example.com", create a values file named "values.xyz-frontend.hostspace.yaml" as following:

ambassador:
  external:
    cert: |
      -----BEGIN CERTIFICATE-----
      Your TLS certificate
      -----END CERTIFICATE-----
    key: |
      -----BEGIN PRIVATE KEY-----
      Your Private Key
      -----END PRIVATE KEY-----

Note the following in the above example:

1. In filename, "xyz" is appCode and "frontend" is service name.
2. YAML structure is similar to the above example where hostname is set.

This newly created values.*.yaml file needs to be uploaded as a Secure file in Azure DevOps at "Pipelines > Library > Secure files".

3. (Optional) Configure pipeline to read values file

In the event that a custom TLS certificate and private key was defined in the previous step, then in this step, configure the CloudOne pipeline so that it will read the secret values.*.yaml file uploaded in the previous step.

In order to do this, configure manifestSupportSteps in azure-pipelines.yml for the desired deployment space as shown in following example.

Example: Continuing the above example, configure azure-pipelines.yml as following in order to read the values.*.yaml file.

...
      prod:
      - spacename: xyz-prd-1
        ref: prd1
        dependsOn:
        - st1
        manifestSupportSteps:
        - task: DownloadSecureFile@1
          name: tlsConfig
          inputs:
          secureFile: values.xyz-frontend.hostspace.yaml
        helm:
          overrideFiles: |
            xyz-frontend/values.hostspace.yaml
            $(tlsConfig.secureFilePath)
...

4. Configure helm chart with TLSContext

In order to configure TLS termination with Ambassador, provide a TLSContext CRD with TLS certificate and private key.

If TLS terminations need to be configured for a CloudOne Nginx AppStack within a provided helm chart, modify ambassador.yaml to create the TLSContext with Secret as following:

{{- $scheme := required "service.scheme is required"  .Values.service.scheme -}}
{{- $fullName := include "nginx.fullname" . -}}
{{- $labels := include "nginx.labels" . -}}

{{- range $id, $amb:= .Values.ambassador }}
{{- if $amb.enabled -}}
{{- $req := printf "Value for ambassador.%s.domain is required" $id  -}}
{{- $domain := required $req $amb.domain -}}
{{- $name := printf "%s-%s" $fullName $id  }}

{{- if $amb.hostname -}}
---
apiVersion: v1
kind: Secret
type: kubernetes.io/tls
metadata:
  name: {{ $name }}-cert
  labels:
{{ include "nginx.labels" $ | indent 4 }}
data:
  tls.crt: {{ $amb.cert | b64enc }}
  tls.key: {{ $amb.key | b64enc }}
---
apiVersion: getambassador.io/v2
kind: TLSContext
metadata:
  name: {{ $name }}-context
  labels:
{{ include "nginx.labels" $ | indent 4 }}
spec:
  ambassador_id: {{ $id }}
  hosts:
  - {{ $amb.hostname }}
  secret: {{ $name }}-cert
{{- end }}

---
apiVersion: getambassador.io/v2
kind: Mapping
metadata:
  name: {{ $name }}
  labels:
{{ include "nginx.labels" $ | indent 4 }}
spec:
  ambassador_id: {{ $id }}
  prefix: {{ $amb.prefix | default '/' }}
  host: {{ $amb.hostname | default (printf "%s-%s.%s" $fullName $.Release.Namespace $domain) | quote }}
  service: {{ printf "%s://%s:%s" $scheme $fullName ( $.Values.service.port | toString ) | quote}}
  weight: {{ $.Values.ambassador.traffic.weight | default 100 }}
{{- end }}
{{- end }}

Note that Helm uses the hostname configured in step 1 and creates a TLSContext and a Secret to hold the TLS certificate and private key provided by the pipeline or optionally from the definition in the values.*.yaml file described in steps 2 and 3.