From 6775deef9b1aa709e9c9eea48ceb8ddcff6e259b Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 4 Oct 2020 16:51:00 +0200 Subject: [PATCH] update docs and examples to use shorter config secret syntax --- app-config.yaml | 111 ++++++------------ docs/auth/auth-backend-classes.md | 17 +-- docs/conf/index.md | 3 +- docs/conf/writing.md | 33 +++--- .../software-catalog/configuration.md | 18 +-- .../software-templates/installation.md | 9 +- docs/plugins/proxying.md | 3 +- docs/tutorials/quickstart-app-auth.md | 9 +- .../templates/default-app/app-config.yaml.hbs | 24 ++-- plugins/circleci/README.md | 3 +- plugins/jenkins/README.md | 3 +- plugins/rollbar-backend/README.md | 3 +- plugins/rollbar/README.md | 3 +- 13 files changed, 84 insertions(+), 155 deletions(-) diff --git a/app-config.yaml b/app-config.yaml index ac327f04a9..227e188ec1 100644 --- a/app-config.yaml +++ b/app-config.yaml @@ -18,23 +18,20 @@ proxy: target: https://circleci.com/api/v1.1 headers: Circle-Token: - $secret: - env: CIRCLECI_AUTH_TOKEN + $env: CIRCLECI_AUTH_TOKEN '/jenkins/api': target: http://localhost:8080 headers: Authorization: - $secret: - env: JENKINS_BASIC_AUTH_HEADER + $env: JENKINS_BASIC_AUTH_HEADER '/travisci/api': target: https://api.travis-ci.com changeOrigin: true headers: Authorization: - $secret: - env: TRAVISCI_AUTH_TOKEN + $env: TRAVISCI_AUTH_TOKEN travis-api-version: 3 organization: @@ -52,8 +49,7 @@ sentry: rollbar: organization: spotify accountToken: - $secret: - env: ROLLBAR_ACCOUNT_TOKEN + $env: ROLLBAR_ACCOUNT_TOKEN newrelic: api: @@ -71,38 +67,31 @@ integrations: github: - host: github.com token: - $secret: - env: GITHUB_PRIVATE_TOKEN + $env: GITHUB_PRIVATE_TOKEN ### Example for how to add your GitHub Enterprise instance using the API: # - host: ghe.example.net # apiBaseUrl: https://ghe.example.net/api/v3 # token: - # $secret: - # env: GHE_PRIVATE_TOKEN + # $env: GHE_PRIVATE_TOKEN ### Example for how to add your GitHub Enterprise instance using raw HTTP fetches (token is optional): # - host: ghe.example.net # rawBaseUrl: https://ghe.example.net/raw # token: - # $secret: - # env: GHE_PRIVATE_TOKEN + # $env: GHE_PRIVATE_TOKEN gitlab: - host: gitlab.com token: - $secret: - env: GITLAB_PRIVATE_TOKEN + $env: GITLAB_PRIVATE_TOKEN bitbucket: - host: bitbucket.org username: - $secret: - env: BITBUCKET_USERNAME + $env: BITBUCKET_USERNAME appPassword: - $secret: - env: BITBUCKET_APP_PASSWORD + $env: BITBUCKET_APP_PASSWORD azure: - host: dev.azure.com token: - $secret: - env: AZURE_PRIVATE_TOKEN + $env: AZURE_PRIVATE_TOKEN catalog: rules: @@ -113,14 +102,12 @@ catalog: providers: - target: https://github.com token: - $secret: - env: GITHUB_PRIVATE_TOKEN + $env: GITHUB_PRIVATE_TOKEN #### Example for how to add your GitHub Enterprise instance using the API: # - target: https://ghe.example.net # apiBaseUrl: https://ghe.example.net/api/v3 # token: - # $secret: - # env: GHE_PRIVATE_TOKEN + # $env: GHE_PRIVATE_TOKEN locations: # Backstage example components @@ -142,104 +129,80 @@ catalog: scaffolder: github: token: - $secret: - env: GITHUB_ACCESS_TOKEN + $env: GITHUB_ACCESS_TOKEN visibility: public # or 'internal' or 'private' gitlab: api: baseUrl: https://gitlab.com token: - $secret: - env: GITLAB_ACCESS_TOKEN + $env: GITLAB_ACCESS_TOKEN azure: baseUrl: https://dev.azure.com/{your-organization} api: token: - $secret: - env: AZURE_PRIVATE_TOKEN + $env: AZURE_PRIVATE_TOKEN auth: providers: google: development: clientId: - $secret: - env: AUTH_GOOGLE_CLIENT_ID + $env: AUTH_GOOGLE_CLIENT_ID clientSecret: - $secret: - env: AUTH_GOOGLE_CLIENT_SECRET + $env: AUTH_GOOGLE_CLIENT_SECRET github: development: clientId: - $secret: - env: AUTH_GITHUB_CLIENT_ID + $env: AUTH_GITHUB_CLIENT_ID clientSecret: - $secret: - env: AUTH_GITHUB_CLIENT_SECRET + $env: AUTH_GITHUB_CLIENT_SECRET enterpriseInstanceUrl: - $secret: - env: AUTH_GITHUB_ENTERPRISE_INSTANCE_URL + $env: AUTH_GITHUB_ENTERPRISE_INSTANCE_URL gitlab: development: clientId: - $secret: - env: AUTH_GITLAB_CLIENT_ID + $env: AUTH_GITLAB_CLIENT_ID clientSecret: - $secret: - env: AUTH_GITLAB_CLIENT_SECRET + $env: AUTH_GITLAB_CLIENT_SECRET audience: - $secret: - env: GITLAB_BASE_URL + $env: GITLAB_BASE_URL saml: entryPoint: 'http://localhost:7001/' issuer: 'passport-saml' okta: development: clientId: - $secret: - env: AUTH_OKTA_CLIENT_ID + $env: AUTH_OKTA_CLIENT_ID clientSecret: - $secret: - env: AUTH_OKTA_CLIENT_SECRET + $env: AUTH_OKTA_CLIENT_SECRET audience: - $secret: - env: AUTH_OKTA_AUDIENCE + $env: AUTH_OKTA_AUDIENCE oauth2: development: clientId: - $secret: - env: AUTH_OAUTH2_CLIENT_ID + $env: AUTH_OAUTH2_CLIENT_ID clientSecret: - $secret: - env: AUTH_OAUTH2_CLIENT_SECRET + $env: AUTH_OAUTH2_CLIENT_SECRET authorizationUrl: - $secret: - env: AUTH_OAUTH2_AUTH_URL + $env: AUTH_OAUTH2_AUTH_URL tokenUrl: - $secret: - env: AUTH_OAUTH2_TOKEN_URL + $env: AUTH_OAUTH2_TOKEN_URL auth0: development: clientId: - $secret: - env: AUTH_AUTH0_CLIENT_ID + $env: AUTH_AUTH0_CLIENT_ID clientSecret: - $secret: - env: AUTH_AUTH0_CLIENT_SECRET + $env: AUTH_AUTH0_CLIENT_SECRET domain: - $secret: - env: AUTH_AUTH0_DOMAIN + $env: AUTH_AUTH0_DOMAIN microsoft: development: clientId: - $secret: - env: AUTH_MICROSOFT_CLIENT_ID + $env: AUTH_MICROSOFT_CLIENT_ID clientSecret: - $secret: - env: AUTH_MICROSOFT_CLIENT_SECRET + $env: AUTH_MICROSOFT_CLIENT_SECRET tenantId: - $secret: - env: AUTH_MICROSOFT_TENANT_ID + $env: AUTH_MICROSOFT_TENANT_ID costInsights: engineerCost: 200000 products: diff --git a/docs/auth/auth-backend-classes.md b/docs/auth/auth-backend-classes.md index 4ccee8ede9..9dc677b439 100644 --- a/docs/auth/auth-backend-classes.md +++ b/docs/auth/auth-backend-classes.md @@ -67,26 +67,21 @@ auth: google: development: clientId: - $secret: - env: AUTH_GOOGLE_CLIENT_ID + $env: AUTH_GOOGLE_CLIENT_ID clientSecret: - $secret: - env: AUTH_GOOGLE_CLIENT_SECRET + $env: AUTH_GOOGLE_CLIENT_SECRET github: development: clientId: - $secret: - env: AUTH_GITHUB_CLIENT_ID + $env: AUTH_GITHUB_CLIENT_ID clientSecret: - $secret: - env: AUTH_GITHUB_CLIENT_SECRET + $env: AUTH_GITHUB_CLIENT_SECRET enterpriseInstanceUrl: - $secret: - env: AUTH_GITHUB_ENTERPRISE_INSTANCE_URL + $env: AUTH_GITHUB_ENTERPRISE_INSTANCE_URL gitlab: development: clientId: - $secret: + $env: ... ``` diff --git a/docs/conf/index.md b/docs/conf/index.md index 83eff50a7d..e1dfc30582 100644 --- a/docs/conf/index.md +++ b/docs/conf/index.md @@ -18,7 +18,8 @@ allowing for customization. Configuration is stored in `app-config.yaml` files, with support for suffixes such as `app-config.production.yaml` to override values for specific environments. The configuration files themselves contain plain YAML, but with -support for loading in secrets from various sources using a `$secret` key. +support for loading in secrets from various sources using for example `$env` and +`$file` keys. It is also possible to supply configuration through environment variables, for example `APP_CONFIG_app_baseUrl=https://staging.example.com`. However these diff --git a/docs/conf/writing.md b/docs/conf/writing.md index 6d338e586d..5564e780bb 100644 --- a/docs/conf/writing.md +++ b/docs/conf/writing.md @@ -90,18 +90,17 @@ order: ## Secrets -Secrets are supported via a special `$secret` key, which in turn provides a -number of different ways to read in secrets. To load a configuration value as a -secret, supply an object with a single `$secret` key, and within that supply an -object that describes how the secret is loaded. For example, the following will -read the config key `backend.mySecretKey` from the environment variable -`MY_SECRET_KEY`: +Secrets are supported via a special secret keys that are prefixed with `$`, +which in turn provides a number of different ways to read in secrets. To load a +configuration value as a secret, supply an object with one of the special secret +keys, for example `$env` or `$file`. A full list of supported secret keys can be +found below. For example, the following will read the config key +`backend.mySecretKey` from the environment variable `MY_SECRET_KEY`: ```yaml backend: mySecretKey: - $secret: - env: MY_SECRET_KEY + $env: MY_SECRET_KEY ``` With the above configuration, calling `config.getString('backend.mySecretKey')` @@ -123,8 +122,7 @@ This reads a secret from an environment variable. For example, the following config loads the secret from the `MY_SECRET` env var. ```yaml -$secret: - env: MY_SECRET +$env: MY_SECRET ``` ### File Secrets @@ -135,22 +133,19 @@ following reads the contents of `my-secret.txt` relative to the config file itself: ```yaml -$secret: - file: ./my-secret.txt +$file: ./my-secret.txt ``` ### Data File Secrets This reads secrets from a path within a JSON-like data file. The file path -behaves similar to file secrets, but in addition a `path` is used to point to a -specific value inside the file. Supported file extensions are `.json`, `.yaml`, -and `.yml`. For example, the following would read out `my-secret-key` from -`my-secrets.json`: +behaves similar to file secrets, but with the addition of a url fragment that is +used to point to a specific value inside the file. Supported file extensions are +`.json`, `.yaml`, and `.yml`. For example, the following would read out +`my-secret-key` from `my-secrets.json`: ```yaml -$secret: - data: ./my-secrets.json - path: deployment.key +$data: ./my-secrets.json#deployment.key # my-secrets.json { diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index ba5e36ab5d..46de2d3d67 100644 --- a/docs/features/software-catalog/configuration.md +++ b/docs/features/software-catalog/configuration.md @@ -23,32 +23,26 @@ integrations: github: - host: github.com token: - $secret: - env: GITHUB_TOKEN + $env: GITHUB_TOKEN - host: ghe.example.net apiBaseUrl: https://ghe.example.net/api/v3 rawBaseUrl: https://ghe.example.net/raw token: - $secret: - env: GHE_TOKEN + $env: GHE_TOKEN gitlab: - host: gitlab.com token: - $secret: - env: GITLAB_TOKEN + $env: GITLAB_TOKEN bitbucket: - host: bitbucket.org username: - $secret: - env: BITBUCKET_USERNAME + $env: BITBUCKET_USERNAME appPassword: - $secret: - env: BITBUCKET_APP_PASSWORD + $env: BITBUCKET_APP_PASSWORD azure: - host: dev.azure.com token: - $secret: - env: AZURE_TOKEN + $env: AZURE_TOKEN ``` Each key under `integrations` is a separate configuration for each external diff --git a/docs/features/software-templates/installation.md b/docs/features/software-templates/installation.md index 08f1882425..60f73ad0c3 100644 --- a/docs/features/software-templates/installation.md +++ b/docs/features/software-templates/installation.md @@ -232,15 +232,13 @@ instance: scaffolder: github: token: - $secret: - env: GITHUB_ACCESS_TOKEN + $env: GITHUB_ACCESS_TOKEN visibility: public # or 'internal' or 'private' gitlab: api: baseUrl: https://gitlab.com token: - $secret: - env: SCAFFOLDER_GITLAB_PRIVATE_TOKEN + $env: SCAFFOLDER_GITLAB_PRIVATE_TOKEN ``` #### Azure DevOps @@ -257,8 +255,7 @@ scaffolder: baseUrl: https://dev.azure.com/{your-organization} api: token: - $secret: - env: AZURE_PRIVATE_TOKEN + $env: AZURE_PRIVATE_TOKEN ``` ### Running the Backend diff --git a/docs/plugins/proxying.md b/docs/plugins/proxying.md index a691c7f0bc..3d9aa90447 100644 --- a/docs/plugins/proxying.md +++ b/docs/plugins/proxying.md @@ -41,8 +41,7 @@ proxy: target: http://larger.example.com:8080/svc.v1 headers: Authorization: - $secret: - env: EXAMPLE_AUTH_HEADER + $env: EXAMPLE_AUTH_HEADER ``` Each key under the proxy configuration entry is a route to match, below the diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md index 7403f2c2dd..8f6b35617b 100644 --- a/docs/tutorials/quickstart-app-auth.md +++ b/docs/tutorials/quickstart-app-auth.md @@ -72,15 +72,12 @@ auth: github: development: clientId: - $secret: - env: AUTH_GITHUB_CLIENT_ID + $env: AUTH_GITHUB_CLIENT_ID clientSecret: - $secret: - env: AUTH_GITHUB_CLIENT_SECRET + $env: AUTH_GITHUB_CLIENT_SECRET ## uncomment the following three lines if using enterprise # enterpriseInstanceUrl: - # $secret: - # env: AUTH_GITHUB_ENTERPRISE_INSTANCE_URL + # $env: AUTH_GITHUB_ENTERPRISE_INSTANCE_URL ``` 2. Set environment variables in whatever fashion is easiest for you. I chose to diff --git a/packages/create-app/templates/default-app/app-config.yaml.hbs b/packages/create-app/templates/default-app/app-config.yaml.hbs index a179efe982..fb6185d51b 100644 --- a/packages/create-app/templates/default-app/app-config.yaml.hbs +++ b/packages/create-app/templates/default-app/app-config.yaml.hbs @@ -22,22 +22,17 @@ backend: client: pg connection: host: - $secret: - env: POSTGRES_HOST + $env: POSTGRES_HOST port: - $secret: - env: POSTGRES_PORT + $env: POSTGRES_PORT user: - $secret: - env: POSTGRES_USER + $env: POSTGRES_USER password: - $secret: - env: POSTGRES_PASSWORD + $env: POSTGRES_PASSWORD # https://node-postgres.com/features/ssl #ssl: require # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require) #ca: # if you have a CA file and want to verify it you can uncomment this section - # $secret: - # file: /ca/server.crt + # $file: /ca/server.crt {{/if}} proxy: @@ -60,8 +55,7 @@ auth: scaffolder: github: token: - $secret: - env: GITHUB_ACCESS_TOKEN + $env: GITHUB_ACCESS_TOKEN visibility: public # or 'internal' or 'private' catalog: @@ -72,14 +66,12 @@ catalog: providers: - target: https://github.com token: - $secret: - env: GITHUB_PRIVATE_TOKEN + $env: GITHUB_PRIVATE_TOKEN # Example for how to add your GitHub Enterprise instance: # - target: https://ghe.example.net # apiBaseUrl: https://ghe.example.net/api/v3 # token: - # $secret: - # env: GHE_PRIVATE_TOKEN + # $env: GHE_PRIVATE_TOKEN locations: # Backstage example components - type: url diff --git a/plugins/circleci/README.md b/plugins/circleci/README.md index 19c2c35899..d329768514 100644 --- a/plugins/circleci/README.md +++ b/plugins/circleci/README.md @@ -57,8 +57,7 @@ proxy: target: https://circleci.com/api/v1.1 headers: Circle-Token: - $secret: - env: CIRCLECI_AUTH_TOKEN + $env: CIRCLECI_AUTH_TOKEN ``` 5. Get and provide `CIRCLECI_AUTH_TOKEN` as env variable (https://circleci.com/docs/api/#add-an-api-token) diff --git a/plugins/jenkins/README.md b/plugins/jenkins/README.md index 3f5334b94f..565906ca85 100644 --- a/plugins/jenkins/README.md +++ b/plugins/jenkins/README.md @@ -30,8 +30,7 @@ proxy: changeOrigin: true headers: Authorization: - $secret: - env: JENKINS_BASIC_AUTH_HEADER + $env: JENKINS_BASIC_AUTH_HEADER ``` 4. Add an environment variable which contains the Jenkins credentials, (note: use an API token not your password) diff --git a/plugins/rollbar-backend/README.md b/plugins/rollbar-backend/README.md index c221dfd23b..f441efa416 100644 --- a/plugins/rollbar-backend/README.md +++ b/plugins/rollbar-backend/README.md @@ -10,8 +10,7 @@ The following values are read from the configuration file. rollbar: organization: spotify accountToken: - $secret: - env: ROLLBAR_ACCOUNT_TOKEN + $env: ROLLBAR_ACCOUNT_TOKEN ``` _NOTE: The `ROLLBAR_ACCOUNT_TOKEN` environment variable must be set to a read diff --git a/plugins/rollbar/README.md b/plugins/rollbar/README.md index b2d2100dd9..98f2272508 100644 --- a/plugins/rollbar/README.md +++ b/plugins/rollbar/README.md @@ -55,8 +55,7 @@ const ServiceEntityPage = ({ entity }: { entity: Entity }) => ( rollbar: organization: spotify accountToken: - $secret: - env: ROLLBAR_ACCOUNT_TOKEN + $env: ROLLBAR_ACCOUNT_TOKEN ``` 7. Annotate entities with the rollbar project slug