External Account Configuration

This page describes Spinnaker’s external configuration feature. Using external configuration, you can manage account configuration (either complete account configuration, or only secrets such as account passwords) externally from Spinnaker.

External configuration uses the open-source Spring Cloud Config project, which includes a configuration server and client libraries to support centralized external configuration in a distributed system. The Config Server connects to a remote configuration repository and serves stored configuration properties to client applications.

Configuration properties can be organized by Spring profile and application name and can be stored in any of a number of backends, including GitHub, HashiCorp Vault, AWS S3, JDBC, CredHub, and others. For more information about Spring Cloud Config, see the documentation .

The following table lists the Spinnaker services that currently incorporate external configuration.

For Clouddriver, support for external configuration was added in Spinnaker 1.15. For Echo and Igor, support was added in Spinnaker 1.16.

Enabling external configuration

To enable external configuration via the Config Server, add Spring Cloud Config configuration properties, which are under spring.cloud.config.server, and include settings for the backend you wish to use.

If you are deploying Spinnaker using Halyard, you can place this file under the ~/.hal/$DEPLOYMENT/profiles directory in the machine on which Halyard is installed, as described in Custom Profiles ($DEPLOYMENT is typically default). If you are deploying Spinnaker manually, you might place this configuration in a YAML file called spinnakerconfig.yml, alongside your spinnaker.yml file.

Using a Git backend

To use a Git backend, configure the settings under spring.cloud.config.server.git. Your configuration might look like the following example:

spring:
  profiles:
    include: git
  cloud:
    config:
      server:
        git:
          uri: https://github.com/example/spinnaker-config
          basedir: /tmp/config-repo
          refresh-rate: 10

The repository will be cloned to the directory specified by the git.basedir property. If using multiple Git repositories, you must give each repository a unique value for basedir.

Using a Vault backend

To use a HashiCorp Vault backend, configure the settings under spring.cloud.config.server.vault. Your configuration might look like the following example:

spring:
  profiles:
    include: vault
  cloud:
    config:
      server:
        vault:
          host: config-vault.example.com
          port: 8200
          backend: secret
          kvVersion: 2
          defaultKey: clouddriver
          token: [vault access token]

The above example configures authentication for Vault using using a static authentication token, via the setting of the spring.cloud.config.server.vault.token property. Starting with Spinnaker 1.18, you can use other methods of configuring authentication for Vault. See the relevant Spring Cloud Config Server documentation for more information.

Using an S3 backend

To use an AWS S3 backend, enable the awss3 profile and configure the settings under spring.cloud.config.server.awss3. Your configuration might look like the following example:

spring:
  profiles:
    include: awss3
  cloud:
    config:
      server:
        awss3:
          region: us-west-2
          bucket: my-bucket

To configure authentication, you must use AWS’s Default Credential Provider Chain. See the AWS SDK documentation for more information.

For information about configuring other supported Config Server backends, see the Spring Cloud Config Server documentation .

Managing external configuration

You can use the Config Server to manage all of your account configuration (bypassing Halyard), or to manage secrets used by Halyard account configuration. You can also use the Config Server to retrieve configuration files or encrypted configuration properties.

Complete account configuration

If you wish to use external configuration instead of Halyard to store complete configuration for your accounts, you can move the account configuration to files stored in a Config Server backend, such as a Git repository or HashiCorp Vault server.

To store complete account configuration in Git, create a Git repository and within it, place a file named spinnaker.yml. The file should contain the account configuration, as in the following example of Echo configuration for a Pub/Sub account:

pubsub:
  enabled: true
  google:
    enabled: true
    pubsubType: GOOGLE
    subscriptions:
    - name: my-gcs-subscription
      project: my-project
      subscriptionName: my-gcs-subscription
      jsonPath: /path/to/my-gce-account.json
      ackDeadlineSeconds: 10
      messageFormat: GCS
    publishers: []

To store complete account configuration in HashiCorp Vault, create a JSON file (for example, echo.json) containing the account configuration, as in the following example:

{
   "pubsub": {
      "enabled": true,
      "google": {
         "enabled": true,
         "pubsubType": "GOOGLE",
         "subscriptions": [
            {
               "name": "my-gcs",
               "project": "My-Project",
               "subscriptionName": "my-gcs-subscription",
               "jsonPath": "/home/spinnaker/.hal/default/staging/dependencies/my-gce-account.json",
               "ackDeadlineSeconds": 10,
               "messageFormat": "GCS"
            }
         ],
         "publishers": []
      }
   }
}

Then use the vault command-line interface tool to store this JSON in Vault:

$ vault kv put secret/echo @echo.json

Secrets

If you wish to use Halyard to manage account configuration but store secrets (such as account passwords) externally, you can move the account secrets into files stored in a Config Server backend, such as a Git repository or HashiCorp Vault server. You can then use Spring property placeholders to reference the secret values.

If you are configuring a Jenkins account in Igor, your spinnaker.yml file might look like the following example:

jenkins:
  enabled: true
  masters:
  - name: my-jenkins-master
    permissions: {}
    address: http://my-jenkins.ci.example.com
    username: myuser
    password: ${ci.my-jenkins.password}

You could add this configuration using the hal CLI, as in the following example:

$ hal config provider jenkins account add \
   my-jenkins-master \
   --address http://my-jenkins.ci.example.com \
   --username myuser \
   --password ${ci.my-jenkins.password}

In the Config Server backend (such as a Git repository), the account secrets file might look like the following example:

ci:
  my-jenkins:
    password: 'secret'

Configuration files

Some account configuration, including configuration for the Kubernetes, Google Compute Engine, and Google App Engine cloud providers in Clouddriver and Google Cloud Pub/Sub accounts in Echo, allows credentials to be loaded from files that are separate from the YAML configuration. You can load these separate files from an external source using the Config Server’s Resource abstraction. In the service YAML configuration, prefix a file path with configserver: to indicate that the file should be retrieved by the Config Server.

External configuration files (such as kubeconfig files and GCP JSON files) can only be loaded from S3 or Git (not from Vault).

If you are configuring a Kubernetes cloud provider account and want to load an external kubeconfig.yml file using Config Server, your account configuration might look like the following example:

kubernetes:
  enabled: true
  accounts:
    - name: default
      kubeconfigFile: configserver:kubeconfig.yml
      dockerRegistries:
        - accountName: dockerhub
          namespaces: []
      context: default

Encrypted values

The Config Server can store encrypted secrets in its backend and decrypt the secret values when serving them to clients. You can use this to store encrypted Spinnaker account secrets in a Config Server backend (such as a Git repository).

To enable Config Server decryption, configure the encryption key in your spinnaker-config-local.yml, along with the Config Server backend configuration properties. You can configure the encryption key using properties under encrypt.

When using Config Server encryption or decryption, your configuration might look like the following example:

spring:
  profiles:
    include: git
  cloud:
    config:
      server:
        git:
          uri: https://github.com/example/spinnaker-config
          basedir: /tmp/config-repo
          refresh-rate: 10
encrypt:
  key: mykey

For more information about using the Config Server’s encryption and decryption features, see the Spring Cloud Config Server documentation .

External configuration refresh

If you have enabled caching , Spinnaker will refresh its external configuration automatically on the same time interval as the Clouddriver agent caches. When using the default in-memory caching, this interval defaults to 60 seconds. When using Redis caching , you can configure this interval using the redis.poll.intervalSeconds property.