From a78631213a55c56dccfbfc142e2141a8b52701a4 Mon Sep 17 00:00:00 2001 From: Ben Jackson Date: Tue, 10 Dec 2024 09:58:53 +1100 Subject: [PATCH] docs: refresh documentation and add a troubleshooting page (#410) * chore: fix variable commands so docs are correct * docs: update configuration docs * docs: add troubleshooting docs * chore: add make docs/serve for local docs viewing --- Makefile | 13 ++ cmd/config.go | 6 +- cmd/config_test.go | 16 +-- cmd/testdata/lagoon.yml | 10 +- cmd/testdata/lagoon.yml.invalid | 10 +- cmd/testdata/lagoon.yml.missing | 4 +- cmd/update.go | 1 + cmd/variables.go | 155 +++++++++++++----------- docs/commands/lagoon_add_variable.md | 42 +++++++ docs/commands/lagoon_update_variable.md | 5 +- docs/config.md | 74 +++++------ docs/index.md | 3 + docs/troubleshooting.md | 129 ++++++++++++++++++++ mkdocs.yml | 2 +- 14 files changed, 325 insertions(+), 145 deletions(-) create mode 100644 docs/commands/lagoon_add_variable.md create mode 100644 docs/troubleshooting.md diff --git a/Makefile b/Makefile index 8969f6b1..3bb3015f 100644 --- a/Makefile +++ b/Makefile @@ -98,3 +98,16 @@ install-linux: install-darwin: cp builds/lagoon-cli-${VERSION}-darwin-amd64 ${ARTIFACT_DESTINATION}/lagoon +# Settings for the MKDocs serving +MKDOCS_IMAGE ?= ghcr.io/amazeeio/mkdocs-material +MKDOCS_SERVE_PORT ?= 8000 + +.PHONY: docs/serve +docs/serve: + @echo "Starting container to serve documentation" + @docker pull $(MKDOCS_IMAGE) + @docker run --rm -it \ + -p 127.0.0.1:$(MKDOCS_SERVE_PORT):$(MKDOCS_SERVE_PORT) \ + -v ${PWD}:/docs \ + --entrypoint sh $(MKDOCS_IMAGE) \ + -c 'mkdocs serve -s --dev-addr=0.0.0.0:$(MKDOCS_SERVE_PORT) -f mkdocs.yml' \ No newline at end of file diff --git a/cmd/config.go b/cmd/config.go index e012b958..fe651ea1 100644 --- a/cmd/config.go +++ b/cmd/config.go @@ -354,10 +354,10 @@ func readLagoonConfig(lc *lagoon.Config, file string) error { // configuration to point to the amazeeio lagoon instance if yesNo(fmt.Sprintf("Config file '%s' does not exist, do you want to create it with defaults?", file)) { l := lagoon.Context{ - GraphQL: "https://api.lagoon.amazeeio.cloud/graphql", - HostName: "ssh.lagoon.amazeeio.cloud", + GraphQL: "https://api.amazeeio.cloud/graphql", + HostName: "token.amazeeio.cloud", Token: "", - Port: "32222", + Port: "22", UI: "https://dashboard.amazeeio.cloud", Kibana: "https://logs.amazeeio.cloud/", } diff --git a/cmd/config_test.go b/cmd/config_test.go index 0dbb7984..4d29d95a 100644 --- a/cmd/config_test.go +++ b/cmd/config_test.go @@ -1,6 +1,7 @@ package cmd import ( + "fmt" "reflect" "testing" @@ -23,11 +24,11 @@ func TestConfigRead(t *testing.T) { Default: "amazeeio", Lagoons: map[string]lagoon.Context{ "amazeeio": { - GraphQL: "https://api.lagoon.amazeeio.cloud/graphql", - HostName: "ssh.lagoon.amazeeio.cloud", - Kibana: "https://logs-db-ui-lagoon-master.ch.amazee.io/", - UI: "https://ui-lagoon-master.ch.amazee.io", - Port: "32222", + GraphQL: "https://api.amazeeio.cloud/graphql", + HostName: "token.amazeeio.cloud", + Kibana: "https://logs.amazeeio.cloud/", + UI: "https://dashboard.amazeeio.cloud", + Port: "22", }, }, UpdateCheckDisable: false, @@ -49,8 +50,8 @@ func TestConfigRead(t *testing.T) { Default: "amazeeio", Lagoons: map[string]lagoon.Context{ "amazeeio": { - Kibana: "https://logs-db-ui-lagoon-master.ch.amazee.io/", - UI: "https://ui-lagoon-master.ch.amazee.io", + Kibana: "https://logs.amazeeio.cloud/", + UI: "https://dashboard.amazeeio.cloud", }, }, UpdateCheckDisable: false, @@ -66,6 +67,7 @@ func TestConfigRead(t *testing.T) { tt.Fatal(err) } } + fmt.Println(lc, tc.expect) if !reflect.DeepEqual(lc, tc.expect) { tt.Fatalf("Read config does not match expected config") } diff --git a/cmd/testdata/lagoon.yml b/cmd/testdata/lagoon.yml index 54a645a1..d524badd 100644 --- a/cmd/testdata/lagoon.yml +++ b/cmd/testdata/lagoon.yml @@ -2,10 +2,10 @@ current: amazeeio default: amazeeio lagoons: amazeeio: - graphql: https://api.lagoon.amazeeio.cloud/graphql - hostname: ssh.lagoon.amazeeio.cloud - kibana: https://logs-db-ui-lagoon-master.ch.amazee.io/ - port: 32222 - ui: https://ui-lagoon-master.ch.amazee.io + graphql: https://api.amazeeio.cloud/graphql + hostname: token.amazeeio.cloud + kibana: https://logs.amazeeio.cloud/ + port: 22 + ui: https://dashboard.amazeeio.cloud updatecheckdisable: false environmentfromdirectory: false \ No newline at end of file diff --git a/cmd/testdata/lagoon.yml.invalid b/cmd/testdata/lagoon.yml.invalid index 2356de3f..d74ae715 100644 --- a/cmd/testdata/lagoon.yml.invalid +++ b/cmd/testdata/lagoon.yml.invalid @@ -2,8 +2,8 @@ current: amazeeio default: amazeeio lagoons: amazeeio: - graphql: https://api.lagoon.amazeeio.cloud/graphql - hostname: ssh.lagoon.amazeeio.cloud - kibana: https://logs-db-ui-lagoon-master.ch.amazee.io/ - port: 32222 - ui: https://ui-lagoon-master.ch.amazee.io + graphql: https://api.amazeeio.cloud/graphql + hostname: token.amazeeio.cloud + kibana: https://logs.amazeeio.cloud/ + port: 22 + ui: https://dashboard.amazeeio.cloud diff --git a/cmd/testdata/lagoon.yml.missing b/cmd/testdata/lagoon.yml.missing index 6b17caf8..a9edf28e 100644 --- a/cmd/testdata/lagoon.yml.missing +++ b/cmd/testdata/lagoon.yml.missing @@ -2,5 +2,5 @@ current: amazeeio default: amazeeio lagoons: amazeeio: - kibana: https://logs-db-ui-lagoon-master.ch.amazee.io/ - ui: https://ui-lagoon-master.ch.amazee.io + kibana: https://logs.amazeeio.cloud/ + ui: https://dashboard.amazeeio.cloud diff --git a/cmd/update.go b/cmd/update.go index 12106614..678954ca 100644 --- a/cmd/update.go +++ b/cmd/update.go @@ -30,4 +30,5 @@ func init() { updateCmd.AddCommand(updateDeployTargetConfigCmd) updateCmd.AddCommand(updateDeployTargetCmd) updateCmd.AddCommand(updateOrganizationCmd) + updateCmd.AddCommand(updateVariableCmd) } diff --git a/cmd/variables.go b/cmd/variables.go index 4a5a2714..d096661e 100644 --- a/cmd/variables.go +++ b/cmd/variables.go @@ -20,81 +20,93 @@ var addVariableCmd = &cobra.Command{ PreRunE: func(_ *cobra.Command, _ []string) error { return validateTokenE(cmdLagoon) }, - RunE: func(cmd *cobra.Command, args []string) error { - debug, err := cmd.Flags().GetBool("debug") - if err != nil { - return err - } - varName, err := cmd.Flags().GetString("name") - if err != nil { - return err - } - varValue, err := cmd.Flags().GetString("value") - if err != nil { - return err - } - varScope, err := cmd.Flags().GetString("scope") - if err != nil { - return err - } - if err := requiredInputCheck("Project name", cmdProjectName, "Variable name", varName); err != nil { - return err - } + RunE: addOrUpdateVariable, +} - current := lagoonCLIConfig.Current - token := lagoonCLIConfig.Lagoons[current].Token - lc := lclient.New( - lagoonCLIConfig.Lagoons[current].GraphQL, - lagoonCLIVersion, - lagoonCLIConfig.Lagoons[current].Version, - &token, - debug) +var updateVariableCmd = &cobra.Command{ + Use: "variable", + Aliases: []string{"v"}, + Short: "Add or update a variable to an environment or project", + PreRunE: func(_ *cobra.Command, _ []string) error { + return validateTokenE(cmdLagoon) + }, + RunE: addOrUpdateVariable, +} + +func addOrUpdateVariable(cmd *cobra.Command, args []string) error { + debug, err := cmd.Flags().GetBool("debug") + if err != nil { + return err + } + varName, err := cmd.Flags().GetString("name") + if err != nil { + return err + } + varValue, err := cmd.Flags().GetString("value") + if err != nil { + return err + } + varScope, err := cmd.Flags().GetString("scope") + if err != nil { + return err + } + if err := requiredInputCheck("Project name", cmdProjectName, "Variable name", varName); err != nil { + return err + } + + current := lagoonCLIConfig.Current + token := lagoonCLIConfig.Lagoons[current].Token + lc := lclient.New( + lagoonCLIConfig.Lagoons[current].GraphQL, + lagoonCLIVersion, + lagoonCLIConfig.Lagoons[current].Version, + &token, + debug) - in := &schema.EnvVariableByNameInput{ - Project: cmdProjectName, - Environment: cmdProjectEnvironment, - Scope: schema.EnvVariableScope(strings.ToUpper(varScope)), - Name: varName, - Value: varValue, + in := &schema.EnvVariableByNameInput{ + Project: cmdProjectName, + Environment: cmdProjectEnvironment, + Scope: schema.EnvVariableScope(strings.ToUpper(varScope)), + Name: varName, + Value: varValue, + } + envvar, err := lagoon.AddOrUpdateEnvVariableByName(context.TODO(), in, lc) + if err != nil { + return err + } + + if envvar.ID != 0 { + data := []output.Data{} + env := []string{ + returnNonEmptyString(fmt.Sprintf("%v", envvar.ID)), + returnNonEmptyString(fmt.Sprintf("%v", cmdProjectName)), } - envvar, err := lagoon.AddOrUpdateEnvVariableByName(context.TODO(), in, lc) - if err != nil { - return err + if cmdProjectEnvironment != "" { + env = append(env, returnNonEmptyString(fmt.Sprintf("%v", cmdProjectEnvironment))) } - - if envvar.ID != 0 { - data := []output.Data{} - env := []string{ - returnNonEmptyString(fmt.Sprintf("%v", envvar.ID)), - returnNonEmptyString(fmt.Sprintf("%v", cmdProjectName)), - } - if cmdProjectEnvironment != "" { - env = append(env, returnNonEmptyString(fmt.Sprintf("%v", cmdProjectEnvironment))) - } - env = append(env, returnNonEmptyString(fmt.Sprintf("%v", envvar.Scope))) - env = append(env, returnNonEmptyString(fmt.Sprintf("%v", envvar.Name))) - env = append(env, returnNonEmptyString(fmt.Sprintf("%v", envvar.Value))) - data = append(data, env) - header := []string{ - "ID", - "Project", - } - if cmdProjectEnvironment != "" { - header = append(header, "Environment") - } - header = append(header, "Scope") - header = append(header, "Name") - header = append(header, "Value") - r := output.RenderOutput(output.Table{ - Header: header, - Data: data, - }, outputOptions) - fmt.Fprintf(cmd.OutOrStdout(), "%s", r) - } else { - return handleNilResults("Variable '%s' remained unchanged\n", cmd, varName) + env = append(env, returnNonEmptyString(fmt.Sprintf("%v", envvar.Scope))) + env = append(env, returnNonEmptyString(fmt.Sprintf("%v", envvar.Name))) + env = append(env, returnNonEmptyString(fmt.Sprintf("%v", envvar.Value))) + data = append(data, env) + header := []string{ + "ID", + "Project", } - return nil - }, + if cmdProjectEnvironment != "" { + header = append(header, "Environment") + } + header = append(header, "Scope") + header = append(header, "Name") + header = append(header, "Value") + r := output.RenderOutput(output.Table{ + Header: header, + Data: data, + }, outputOptions) + fmt.Fprintf(cmd.OutOrStdout(), "%s", r) + } else { + return handleNilResults("Variable '%s' remained unchanged\n", cmd, varName) + } + return nil } var deleteVariableCmd = &cobra.Command{ @@ -150,10 +162,7 @@ var deleteVariableCmd = &cobra.Command{ }, } -var updateVariableCmd = addVariableCmd - func init() { - updateCmd.AddCommand(updateVariableCmd) addVariableCmd.Flags().StringP("name", "N", "", "Name of the variable to add") addVariableCmd.Flags().StringP("value", "V", "", "Value of the variable to add") addVariableCmd.Flags().StringP("scope", "S", "", "Scope of the variable[global, build, runtime, container_registry, internal_container_registry]") diff --git a/docs/commands/lagoon_add_variable.md b/docs/commands/lagoon_add_variable.md new file mode 100644 index 00000000..ced7d9ed --- /dev/null +++ b/docs/commands/lagoon_add_variable.md @@ -0,0 +1,42 @@ +## lagoon add variable + +Add or update a variable to an environment or project + +``` +lagoon add variable [flags] +``` + +### Options + +``` + -h, --help help for variable + -N, --name string Name of the variable to add + -S, --scope string Scope of the variable[global, build, runtime, container_registry, internal_container_registry] + -V, --value string Value of the variable to add +``` + +### Options inherited from parent commands + +``` + --config-file string Path to the config file to use (must be *.yml or *.yaml) + --debug Enable debugging output (if supported) + -e, --environment string Specify an environment to use + --force Force yes on prompts (if supported) + -l, --lagoon string The Lagoon instance to interact with + --no-header No header on table (if supported) + --output-csv Output as CSV (if supported) + --output-json Output as JSON (if supported) + --pretty Make JSON pretty (if supported) + -p, --project string Specify a project to use + --skip-update-check Skip checking for updates + -i, --ssh-key string Specify path to a specific SSH key to use for lagoon authentication + --ssh-publickey string Specify path to a specific SSH public key to use for lagoon authentication using ssh-agent. + This will override any public key identities defined in configuration + --strict-host-key-checking string Similar to SSH StrictHostKeyChecking (accept-new, no, ignore) (default "accept-new") + -v, --verbose Enable verbose output to stderr (if supported) +``` + +### SEE ALSO + +* [lagoon add](lagoon_add.md) - Add a project, or add notifications and variables to projects or environments + diff --git a/docs/commands/lagoon_update_variable.md b/docs/commands/lagoon_update_variable.md index 1f61ee15..379b1213 100644 --- a/docs/commands/lagoon_update_variable.md +++ b/docs/commands/lagoon_update_variable.md @@ -9,10 +9,7 @@ lagoon update variable [flags] ### Options ``` - -h, --help help for variable - -N, --name string Name of the variable to add - -S, --scope string Scope of the variable[global, build, runtime, container_registry, internal_container_registry] - -V, --value string Value of the variable to add + -h, --help help for variable ``` ### Options inherited from parent commands diff --git a/docs/config.md b/docs/config.md index 321b027b..fd73ab92 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1,6 +1,6 @@ # Introduction -By default the CLI is configured to use the `amazeeio` Lagoon. But you can also define additional Lagoons if you need to. +By default the CLI is configured to use the `amazeeio` Lagoon. But you can also define additional Lagoon contexts if you need to. The `.lagoon.yml` file will be installed in your home directory by default @@ -11,85 +11,69 @@ current: amazeeio default: amazeeio lagoons: amazeeio: - graphql: https://api.lagoon.amazeeio.cloud/graphql - hostname: ssh.lagoon.amazeeio.cloud - port: 32222 + graphql: https://api.amazeeio.cloud/graphql + hostname: token.amazeeio.cloud + port: 22 token: ey.....xA ``` There are a few sections to cover off -* `current` is the current Lagoon that you will be using, if you only have the one, it will be `amazeeio` -* `default` is the default Lagoon to use, if you always use a particular Lagoon then you can set your preference as your default -* `lagoons` is where the actual connection parameters are stored for each Lagoon, they all follow the same template. +* `current` is the current Lagoon context that you will be using, if you only have the one, it will be `amazeeio` +* `default` is the default Lagoon context to use, if you always use a particular context then you can set your preference as your default +* `lagoons` is where the actual connection parameters are stored for each Lagoon context, they all follow the same template. * `graphql` is the graphql endpoint - * `hostname` is the ssh hostname - * `port` is the ssh port + * `hostname` is the ssh token hostname + * `port` is the ssh token port * `token` is the graphql token, this is automatically generate the first time you `lagoon login` and will automatically refresh if it expires via ssh. -# Add a Lagoon -If you want to add a different Lagoon to use, then you can use the CLI command to view the flags available +# Add a Lagoon context +If you want to add a different Lagoon context to use, then you can use the CLI command to view the flags available ```bash -lagoon config add --lagoon LagoonName +lagoon config add --lagoon example ``` ## Example ```bash lagoon config add --lagoon amazeeio \ - --graphql https://api.lagoon.amazeeio.cloud/graphql \ - --hostname ssh.lagoon.amazeeio.cloud \ - --port 32222 + --graphql https://api.amazeeio.cloud/graphql \ + --hostname token.amazeeio.cloud \ + --port 22 ``` -# Delete a Lagoon -If you want to remove a Lagoon, you can use +# Delete a Lagoon context +If you want to remove a Lagoon context, you can use ```bash -lagoon config delete --lagoon LagoonName +lagoon config delete --lagoon example ``` ## Example ```bash lagoon config delete --lagoon amazeeio ``` -# Change default Lagoon -If you add additional Lagoons, you can select which one is the default you want to use by running +# Change default Lagoon context +If you add additional Lagoon contexts, you can select which one is the default you want to use by running ```bash -lagoon config default --lagoon LagoonName +lagoon config default --lagoon example ``` ## Example ```bash lagoon config default --lagoon amazeeio ``` -# Use a different Lagoon -If you want to temporarily use a different Lagoon, when you run any commands you can specify the flag `--lagoon` or `-l` and then the name of the Lagoon +# Use a different Lagoon context +If you want to temporarily use a different Lagoon context, when you run any commands you can specify the flag `--lagoon` or `-l` and then the name of the context ## Example ```bash -lagoon --lagoon mylagoon list projects +lagoon --lagoon example list projects ``` -# View Lagoons -You can view all the Lagoons you have configured by running +# View Lagoon contexts +You can view all the Lagoon contexts you have configured by running ```bash lagoon config list ``` Output ```yaml -You have the following lagoons configured: -Name: amazeeio - - Hostname: ssh.lagoon.amazeeio.cloud - - GraphQL: https://api.lagoon.amazeeio.cloud/graphql - - Port: 32222 -Name: mylagoon - - Hostname: ssh.mylagoon.example - - GraphQL: https://api.mylagoon.example/graphql - - Port: 32000 -Name: local - - Hostname: localhost - - GraphQL: http://localhost:3000/graphql - - Port: 2020 - -Your default lagoon is: -Name: local - -Your current lagoon is: -Name: local +NAME VERSION GRAPHQL SSH-HOSTNAME SSH-PORT SSH-KEY +amazeeio(default)(current) v2.22.0 https://api.amazeeio.cloud/graphql token.amazeeio.cloud 22 - +example v2.22.0 https://api.example.com/graphql token.example.com 22 - ``` diff --git a/docs/index.md b/docs/index.md index ff25deba..57bad822 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,6 +9,9 @@ If you run the CLI in a directory that has a valid `.lagoon.yml` and `docker-com # Requirements To use this CLI, you need an account in the Lagoon that you wish to communicate with, and your SSH key needs to be associated to your account. +# Problems? +If you experience any problems, check out the [troubleshooting](./troubleshooting.md) page first. + # Installation The preferred method to install is via [Homebrew](https://brew.sh/). ``` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..38a9e0dd --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,129 @@ +This page attempts to describe some common problems and provide basic troubleshooting guides on what the issue could be and how to attempt a resolution. + +Since every issue can be slightly different, there may be cases where some or none of the steps outlined can help. In these cases, you may have encountered a bug with the CLI or the Lagoon API. Before raising an issue, it is important to try and determine if the issue is related to the API or the CLI. + +# Raising Issues +If raising issues against the CLI, please ensure you include which [version](commands/lagoon_version.md) of the CLI you're using in your report. + +If your issues appears to be permissions or API related, you may need to consult with your hosting provider before raising any issues. + +# Common Problems + +## Refresh token +Sometimes simply refreshing your auth token can help. + +Use [lagoon login](commands/lagoon_login.md) to attempt to retrieve a new token. + +You can also use the flag `--verbose` to see information about the authentication attempt being made and which keys may be being used. + +```bash title="verbose login example" +$ lagoon login --verbose +ssh: attempting connection using any keys in ssh-agent + +$ lagoon login --verbose --ssh-publickey /home/user/.ssh/id_ed25519.pub +ssh: attempting connection using identity file public key: /home/user/.ssh/id_ed25519.pub + +$ lagoon login --verbose --ssh-key /home/user/.ssh/id_ed25519 +ssh: attempting connection using private key: /home/user/.ssh/id_ed25519 +``` + +## SSH keys +The CLI will prefer to use your ssh-agent when providing keys to the authentication endpoint. If you haven't got any keys in your ssh-agent, the CLI will fall back to checking `~/.ssh/id_rsa`. + +!!! Note "Which keys are in my agent?" + You can check the keys in your ssh-agent using `ssh-add -L` + +Some flags and configurations exist that allow you to force which key in your ssh-agent is used, or which SSH key file you want to use. + +### specific key in agent +If you know which public key you want to use when interacting Lagoon, you can use the following flag + +```bash +--ssh-publickey /path/to/privatekey.pub +``` + +This will attempt to use this key if it is present in your ssh-agent. Alternatively, you can add `publickeyidentities` to your context in your Lagoon CLI configuration file. + +```yaml title="~/.lagoon.yml CLI configuration " +lagoons: + contextname: + publickeyidentities: + - /path/to/privatekey.pub +``` + +### specific private key +If you know which private key you want to use when interacting Lagoon, you can use the following flag + +```bash +--ssh-key /path/to/privatekey +``` + +Alternatively, you can add `sshkey` to your context in your Lagoon CLI configuration file. + +```yaml title="~/.lagoon.yml CLI configuration " +lagoons: + contextname: + sshkey: /path/to/privatekey +``` + +## Unauthorized/permission errors +In the event you experience an unauthorized or permission error, it is important to confirm which user has authenticated against the Lagoon API. + +The CLI provides a command [whoami](commands/lagoon_whoami.md) which will query the Lagoon API to determine which user the API is seeing. + +```title="lagoon whoami" +ID EMAIL FIRSTNAME LASTNAME SSHKEYS +95101742-07f373b0bfe3 bob.johnson@example.com Bob Johnson 3 +``` + +### correct user +If the user returned is the correct user, then you need to ensure that commands you're executing you have permission to do so with. Some things to check: + +* That your user actually has access to the resource (project, environment, group, etc..) that you're interacting with + * check your user with the [list user-groups](commands/lagoon_list_user-groups.md) command (you will only be able to run this for your own user). + * some options are only available to `platform-owners` or `organization` administrators, and you'll get permission errors you can check against [Lagoon RBAC](https://docs.lagoon.sh/interacting/rbac/). +* Ensure you've typed the command and all the flags required correctly. Sometimes a typo can present as a permission error. +* Check that you're using the right command for what you're trying to do, the `--help` flag on any command will provide information that may be helpful. + +### incorrect user +If the user is not the user you're expecting, then it is likely you have multiple user accounts, or multiple SSH keys. To help resolve this, its important to know: + +* How many users you've got +* How many SSH keys you've got +* Which SSH keys are attached to which user + * check your user with the [get user-sshkeys](commands/lagoon_get_user-sshkeys.md) command (you will only be able to run this for your own user). +* If you're using an SSH agent, [which keys are loaded](#ssh-keys) into it +* [Login with verbosity](#refresh-token) enabled to see how the CLI is attempting to authenticate + +## Multiple user accounts or contexts +The CLI supports multiple contexts, think of these as a way to interact with multiple Lagoon instances, or a way to select a user if you have multiple accounts. + +An example of how a configuration file looks for a user with multiple accounts is shown below. See [configuration](config.md) on how to add more contexts, or modify your config file manually. +```yaml title="~/.lagoon.yml Multiple accounts" +current: user1 +default: user1 +lagoons: + user1: + graphql: https://api.example.com/graphql + hostname: ssh.example.com + port: "22" + publickeyidentities: + - /path/to/user1/public.key + user2: + graphql: https://api.example.com/graphql + hostname: ssh.example.com + port: "22" + publickeyidentities: + - /path/to/user2/public.key +``` + +You'll see that there are 2 `lagoons` (or contexts), one for `user1` which the publickey override, and one for `user2` with a different publickey override. + + +### Selecting a context +When you want to use the CLI to perform actions as `user1`, you don't need to provide any flags, as the `default` in this example is `user1`. + +If you need to perform actions as `user2`, you will have to [select a context](./config.md#use-a-different-lagoon-context) or [change the default](./config.md#change-default-lagoon-context). + +!!! Note "Changing context" + Sometimes changing your context could result in a token not refreshing correctly. Firstly attempt a [token refresh](#refresh-token) with your selected context. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index fa9e1583..6fb06549 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,4 +47,4 @@ nav: - Getting Started: index.md - Configuration: config.md - Commands: commands/lagoon.md - - Custom Commands: customcommands.md + - Troubleshooting: troubleshooting.md \ No newline at end of file