Install and Configure Spin CLI

In addition to the UI and API, you can use the spin CLI to manage applications and pipelines

For more information, see the spin CLI Guide

Install spin

One way to manage applications and pipelines as code is through spin .

To acquire spin, do the following:

On Linux

  1. curl -LO https://storage.googleapis.com/spinnaker-artifacts/spin/$(curl -s https://storage.googleapis.com/spinnaker-artifacts/spin/latest)/linux/amd64/spin
  2. chmod +x spin
  3. sudo mv spin /usr/local/bin/spin

On MacOS

  1. curl -LO https://storage.googleapis.com/spinnaker-artifacts/spin/$(curl -s https://storage.googleapis.com/spinnaker-artifacts/spin/latest)/darwin/amd64/spin
  2. chmod +x spin
  3. sudo mv spin /usr/local/bin/spin

On Windows

  1. New-Item -ItemType Directory $env:LOCALAPPDATA\spin -ErrorAction SilentlyContinue
  2. Invoke-WebRequest -OutFile $env:LOCALAPPDATA\spin\spin.exe -UseBasicParsing "https://storage.googleapis.com/spinnaker-artifacts/spin/$([System.Text.Encoding]::ASCII.GetString((Invoke-WebRequest https://storage.googleapis.com/spinnaker-artifacts/spin/latest).Content))/windows/amd64/spin.exe"
  3. Unblock-File $env:LOCALAPPDATA\spin\spin.exe
  4. $path = [Environment]::GetEnvironmentVariable("PATH", [EnvironmentVariableTarget]::User) -split ";"
  5. if ($path -inotcontains "$env:LOCALAPPDATA\spin") {
  6. $path += "$env:LOCALAPPDATA\spin"
  7. [Environment]::SetEnvironmentVariable("PATH", $path -join ";", [EnvironmentVariableTarget]::User)
  8. $env:PATH = (([Environment]::GetEnvironmentVariable("PATH", [EnvironmentVariableTarget]::Machine) -split ";") + $path) -join ";"
  9. }

Configure spin

spin reads its configuration from ~/.spin/config.

This configuration file doesn’t exist yet, after you install spin. You need to create it.

  1. Create the directory:
  1. mkdir ~/.spin/
  1. In that directory, create the config file.

    Use example.yaml to populate it.

Currently, all configuration is for authentication mechanisms only.

X.509

spin can be configured with X.509 to authenticate calls against Spinnaker. The configuration block looks like this:

  1. auth:
  2. enabled: true
  3. x509:
  4. certPath: <cert file path>
  5. keyPath: <key file path>

or

  1. auth:
  2. enabled: true
  3. x509:
  4. # Pipes for multi-line strings in yaml.
  5. # Cert and key contents are 64 encoded pem values.
  6. cert: |
  7. <cert>
  8. key: |
  9. <key>

Follow the ssl and x509 guides to generate the X.509 certificate and key files. Refer to the example config and the README for more information about X.509 in spin.

OAuth2

Client ID and Client Secret

spin can be configured with an OAuth2 client ID and secret to authenticate calls against Spinnaker. The configuration block looks like this:

  1. auth:
  2. enabled: true
  3. oauth2:
  4. authUrl: # OAuth2 provider auth url
  5. tokenUrl: # OAuth2 provider token url
  6. clientId: # OAuth2 client id
  7. clientSecret: # OAuth2 client secret
  8. scopes: # Scopes requested for the token
  9. - scope1
  10. - scope2

Read the OAuth setup instructions to see examples for acquiring a clientId/clientSecret from your provider.

This OAuth2 configuration method needs to be initialized once to authenticate with the provider before it can be used for automation. To authenticate, configure OAuth2 as shown above and execute any spin command. You will be prompted to authenticate with your OAuth2 provider and paste an access code. This process involves configuring the callback url to be http://localhost:8085 in order to view and retrieve the access code to be provided to the prompt. spin then exchanges the code for an OAuth2 access/refresh token pair, which it caches in your ~/.spin/config file for future use. All subsequent spin calls will use the cached OAuth2 token for authentication with no user input required. If an OAuth2 access token expires, spin will use the refresh token to renew the access token expiry.

Access and Refresh Token

spin can also be configured with an OAuth2 access token and refresh token in lieu of configuring an OAuth2 client ID and secret. The spin configuration looks like this:

  1. auth:
  2. enabled: true
  3. oauth2:
  4. authUrl: # OAuth2 provider auth url
  5. tokenUrl: # OAuth2 provider token url
  6. # no clientId or clientSecret
  7. scopes: # Scopes requested for the token
  8. - scope1
  9. - scope2
  10. cachedToken:
  11. accesstoken: ${ACCESS_TOKEN} # Note the key capitalization
  12. refreshtoken: ${REFRESH_TOKEN} # Note the key capitalization

This method is OAuth2-provider specific since the workflow to acquire a token is different for each provider. To do so using Google OAuth2 and gcloud:

  1. Authenticate with Google via gcloud auth login.

  2. Use the following commands to acquire the tokens:

  1. ```
  2. ACCESS_TOKEN=$(gcloud auth print-access-token)
  3. REFRESH_TOKEN=$(gcloud auth print-refresh-token)
  4. ```

Google Service Account

If using Google OAuth2, spin can also be configured with a service account . Generate a service account key in JSON format. For more information, see the Google docs . The JSON file should look something like this:

  1. {
  2. "type": "service_account",
  3. "project_id": "project-id",
  4. "private_key_id": "key-id",
  5. "private_key": "-----BEGIN PRIVATE KEY-----\nprivate-key\n-----END PRIVATE KEY-----\n",
  6. "client_email": "service-account-email",
  7. "client_id": "client-id",
  8. "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  9. "token_uri": "https://accounts.google.com/o/oauth2/token",
  10. "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  11. "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/service-account-email"
  12. }

The spin configuration looks like this:

  1. auth:
  2. GoogleServiceAccount:
  3. file: /path/to/key/pair.json

Basic

spin can be configured with basic authentication credentials to authenticate calls against Spinnaker. The configuration block looks like this:

  1. auth:
  2. enabled: true
  3. basic:
  4. username: < username >
  5. password: < password >

LDAP/Active Directory

spin can be configured with LDAP to authenticate calls against Spinnaker. The configuration block looks like this:

  1. auth:
  2. enabled: true
  3. ldap:
  4. username: < username >
  5. password: < password >

Global Flags

spin has a few helpful global flags:

  1. Global Options:
  2. --gate-endpoint Gate (API server) endpoint.
  3. --no-color Removes color from CLI output.
  4. --insecure=false Ignore certificate errors during connection to endpoints.
  5. --quiet=false Squelch non-essential output.
  6. --output <output format> Formats CLI output.

Output Formatting

The global --output flag allows users to manipulate spin‘s output format. By default, spin will print the command output in json. Users can also specify a jsonpath in the output flag to extract nested data from the command output:

  1. spin pipeline get --name pipelineName --application app --output jsonpath="{.stages}"
  2. [
  3. <stages>
  4. ]

spin leverages the kubectl jsonpath libraries to support this. Follow the kubectl documentation for more information about the possible jsonpath arguments.

Last modified July 20, 2021: docs(site): Document hidden google oauth2 service account for spin cli (#130) (6cf9349)