You are viewing version 2.23 of the documentation, which is no longer maintained. For up-to-date documentation, see the latest version.

Configuring mTLS for Spinnaker Services

This guide describes how to enable mutual TLS (mTLS) between Spinnaker services and is building on top of how to enable TLS. Adding mTLS provides additional security for your Spinnaker services since only validated clients can interact with services when mTLS is enabled.


mTLS is a transport level security measure. When a client connects to a server, as in a TLS connection:

  • The server responds with its certificate. Additionally, the server sends a certificate request and a list of Distinguished Names the server recognizes.
  • The client verifies the certificate of the server and responds with its own certificate and the Distinguished Name its certificate was (in)directly signed with.
  • The server verifies the certificate of the client.

To set up TLS, provide the following:

  1. For a server:
  • Certificate and private key
  • Chain of certificates to validate clients
  1. For a client:
  • Certificate and private key to present to the server
  • Chain of certificates to validate the server (if self signed)

For information about TLS, see how to enable TLS.

What you need

In the following sections, you need the same information that you needed for TLS setup:

  • ca.pem (all Golang servers): the CA certificate in PEM format
  • [service].crt (each Golang server): the certificate and optionally the private key of the Golang server in PEM format
  • [service].key (each Golang server): the private key of the Golang server if not bundled with the certificate above
  • [GOSERVICE]_KEY_PASS (each Golang server): the password to the private key of the server
  • truststore.p12 (all Java clients): a PKCS12 truststore with CA certificate imported
  • TRUSTSTORE_PASS (all Java clients): the password to the truststore above
  • [service].p12 (each Java server): a PKCS12 keystore containing the certificate and private key of the server
  • [SERVICE]_KEY_PASS (each Java server): the password to the keystore above

The server certificate will serve as its client certificate to other services. You can generate different certificates and use them in ok-http-client.key-store* (Java) and http.key* (Golang).

To learn how to generate these files, refer to generating certificates.

Configuration (Java services)

Add the following to each Java service profile: <deploy>/profiles/<service>-local.yml in Halyard or under profiles in the SpinnakerService’s profiles:

# Only needed for "server" role
    enabled: true
    key-store: <reference to [service].p12>
    key-store-type: PKCS12
    key-store-password: <[SERVICE]_KEY_PASS>
    trust-store: <reference to ca.p12>
    trust-store-type: PKCS12
    trust-store-password: <TRUSTSTORE_PASS>
    # Roll out with "want" initially
    client-auth: need

# Needed for all Java services
  key-store: <reference to [service].p12>
  key-store-type: PKCS12
  key-store-password: [SERVICE]_KEY_PASS
  trust-store: <reference to truststore.p12>
  trust-store-type: PKCS12
  trust-store-password: <TRUSTSTORE_PASS>

Configuration (Golang services)

    enabled: true
    certFile: <reference to [service].crt>
    keyFile: <reference to [service].key if not included in the certFile's PEM>
    keyPassword: <[GOSERVICE]_KEY_PASS if required>
    cacertFile: <reference to ca.pem>
    # Roll out with "want" initially
    clientAuth: need

  cacertFile: <reference to ca.pem>
  clientCertFile: <reference to [service].crt>
  clientKeyFile: <reference to [service.key]>
  clientKeyPassword: <[GOSERVICE]_KEY_PASS if required>

Changing service endpoints

This section is identical to changing endpoints for TLS.

Changing readiness probe

Change the readiness probe used by Kubernetes from an HTTP request to a TCP probe.


Add the following snippet to each service in SpinnakerService manifest:

kind: SpinnakerService
  name: spinnaker
          useTcpProbe: true


This can be done by adding the following to each service under <deploy>/service-settings/<service>.yml:

  useTcpProbe: true

Important: Version 1.8.2 or later of Halyard Armory is required to support TCP probe.


Apply your changes to your Spinnaker deployment:


kubectl -n <spinnaker namespace> apply -f <SpinnakerService manifest>


hal deploy apply

If Spinnaker services are already using HTTPS, you can roll out mTLS without interruption by making the client certificate optional (want) in server.ssl.client-auth (Java) and server.ssl.clientAuth. Then once all the services are stable, rolling out a new configuration with that value set to need.