From 2a1bfb3e44bcf532756f5b7dea362e1315b4cba1 Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Wed, 12 Oct 2022 10:43:59 -0500 Subject: [PATCH] docs: API tokens & CI automation (#4510) * reword: chore: add CI to dogfood template * use hardcoded URL * use consistent name for tokens * chore: add docs for template change management * add an example * fix case --- .github/workflows/dogfood.yaml | 26 +++++++++++++++++++- cli/tokens.go | 2 +- docs/admin/automation.md | 37 +++++++++++++++++++++++++++++ docs/images/icons/git.svg | 4 ++++ docs/images/icons/plug.svg | 1 + docs/manifest.json | 12 ++++++++++ docs/templates.md | 9 ++----- docs/templates/change-management.md | 23 ++++++++++++++++++ 8 files changed, 105 insertions(+), 9 deletions(-) create mode 100644 docs/admin/automation.md create mode 100644 docs/images/icons/git.svg create mode 100644 docs/images/icons/plug.svg create mode 100644 docs/templates/change-management.md diff --git a/.github/workflows/dogfood.yaml b/.github/workflows/dogfood.yaml index d4b56d8721..1495bff861 100644 --- a/.github/workflows/dogfood.yaml +++ b/.github/workflows/dogfood.yaml @@ -12,7 +12,7 @@ on: workflow_dispatch: jobs: - deploy: + deploy_image: runs-on: ubuntu-latest steps: - name: Get branch name @@ -47,3 +47,27 @@ jobs: tags: "codercom/oss-dogfood:${{ steps.docker-tag-name.outputs.tag }},codercom/oss-dogfood:latest" cache-from: type=registry,ref=codercom/oss-dogfood:latest cache-to: type=inline + deploy_template: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + - name: Get short commit SHA + id: vars + run: echo "::set-output name=sha_short::$(git rev-parse --short HEAD)" + - name: "Install latest Coder" + run: | + curl -L https://coder.com/install.sh | sh + # env: + # VERSION: 0.x + - name: "Push template" + run: | + coder templates push $CODER_TEMPLATE_NAME --directory $CODER_TEMPLATE_DIR --yes --name=$CODER_TEMPLATE_VERSION + env: + # Consumed by Coder CLI + CODER_URL: https://dev.coder.com + CODER_SESSION_TOKEN: ${{ secrets.CODER_SESSION_TOKEN }} + # Template source & details + CODER_TEMPLATE_NAME: ${{ secrets.CODER_TEMPLATE_NAME }} + CODER_TEMPLATE_VERSION: ${{ steps.vars.outputs.sha_short }} + CODER_TEMPLATE_DIR: ./dogfood diff --git a/cli/tokens.go b/cli/tokens.go index 6941116ee6..8719ab3434 100644 --- a/cli/tokens.go +++ b/cli/tokens.go @@ -67,7 +67,7 @@ func createToken() *cobra.Command { cmd.Println(cliui.Styles.Code.Render(strings.TrimSpace(res.Key))) cmd.Println() cmd.Println(cliui.Styles.Wrap.Render( - fmt.Sprintf("You can use this token by setting the --%s CLI flag, the %s environment variable, or the %q HTTP header.", varToken, envSessionToken, codersdk.SessionTokenKey), + fmt.Sprintf("You can use this token by setting the --%s CLI flag, the %s environment variable, or the %q HTTP header.", varToken, envSessionToken, codersdk.SessionCustomHeader), )) return nil diff --git a/docs/admin/automation.md b/docs/admin/automation.md new file mode 100644 index 0000000000..a7eb780026 --- /dev/null +++ b/docs/admin/automation.md @@ -0,0 +1,37 @@ +# Automation + +We recommend automating Coder deployments through the CLI. Examples include [updating templates via CI/CD pipelines](../templates/change-management.md). + +## Tokens + +Long-lived tokens can be generated to perform actions on behalf of your user account: + +```sh +coder tokens create +``` + +## CLI + +You can use tokens with the CLI by setting the `--token` CLI flag or the `CODER_SESSION_TOKEN` +environment variable. + +```sh +export CODER_URL=https://coder.example.com +export CODER_SESSION_TOKEN=***** +coder workspaces ls +``` + +## REST API + +You can use tokens with the Coder's REST API using the `Coder-Session-Token` HTTP header. + +```sh +curl 'https://dev.coder.com/api/v2/workspaces' \ + -H 'Coder-Session-Token: *****' +``` + +> At this time, we do not publish an API reference. However, [codersdk](https://github.com/coder/coder/tree/main/codersdk) can be grepped to find the necessary routes and payloads. + +## Golang SDK + +Coder publishes a public [Golang SDK](https://pkg.go.dev/github.com/coder/coder@main/codersdk) for Coder. This is consumed by the [CLI package](https://github.com/coder/coder/tree/main/cli). diff --git a/docs/images/icons/git.svg b/docs/images/icons/git.svg new file mode 100644 index 0000000000..2f321c5972 --- /dev/null +++ b/docs/images/icons/git.svg @@ -0,0 +1,4 @@ + + + + diff --git a/docs/images/icons/plug.svg b/docs/images/icons/plug.svg new file mode 100644 index 0000000000..fc56e71f3d --- /dev/null +++ b/docs/images/icons/plug.svg @@ -0,0 +1 @@ + diff --git a/docs/manifest.json b/docs/manifest.json index 220a900f8f..1cf16bd323 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -95,6 +95,12 @@ "path": "./templates/authentication.md", "icon_path": "./images/icons/key.svg" }, + { + "title": "Change Management", + "description": "Learn how to source-control templates with git and CI", + "path": "./templates/change-management.md", + "icon_path": "./images/icons/git.svg" + }, { "title": "Resource Metadata", "description": "Learn how to expose resource data to users", @@ -212,6 +218,12 @@ "icon_path": "./images/icons/upgrade.svg", "path": "./admin/upgrade.md" }, + { + "title": "Automation", + "description": "Learn how to automate Coder with the CLI and API", + "icon_path": "./images/icons/plug.svg", + "path": "./admin/automation.md" + }, { "title": "Audit Logs", "description": "Learn how to use Audit Logs in your Coder deployment.", diff --git a/docs/templates.md b/docs/templates.md index fa8ff558bb..5d09b56e02 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -314,14 +314,9 @@ practices: Template permissions can be used to give users and groups access to specific templates. [Learn more about RBAC](./admin/rbac.md). -## Change Management - -We recommend source controlling your templates as you would other code. - -CI is as simple as running `coder templates push` with the appropriate -credentials. - ## Next Steps - Learn about [Authentication & Secrets](templates/authentication.md) +- Learn about [Change Management](templates/change-management.md) +- Learn about [Resource Metadata](templates/resource-metadata.md) - Learn about [Workspaces](workspaces.md) diff --git a/docs/templates/change-management.md b/docs/templates/change-management.md new file mode 100644 index 0000000000..afe4db1992 --- /dev/null +++ b/docs/templates/change-management.md @@ -0,0 +1,23 @@ +# Template Change Management + +We recommend source controlling your templates as you would other code. [Install Coder](../install/) in CI/CD pipelines to push new template versions. + +```sh +# Install the Coder CLI +curl -L https://coder.com/install.sh | sh +# curl -L https://coder.com/install.sh | sh -s -- --version=0.x + +# To create API tokens, use `coder tokens create`. +# These variables are consumed by Coder +export CODER_URL=https://coder.example.com +export CODER_SESSION_TOKEN=***** + +# Template details +export CODER_TEMPLATE_NAME=kubernetes +export CODER_TEMPLATE_DIR=.coder/templates/kubernetes +export CODER_TEMPLATE_VERSION=$(git rev-parse --short HEAD) + +coder templates push --yes $CODER_TEMPLATE_NAME \ + --directory $CODER_TEMPLATE_DIR \ + --name=$CODER_TEMPLATE_VERSION # Version name is optional +```