diff --git a/AUTHENTICATION.md b/AUTHENTICATION.md index 170b2d9e2..f88cb3883 100644 --- a/AUTHENTICATION.md +++ b/AUTHENTICATION.md @@ -5,7 +5,7 @@ This document describes how you can configure authentication for the STACKIT CLI ## Service account You can use a [service account](https://docs.stackit.cloud/stackit/en/service-accounts-134415819.html) to authenticate to the STACKIT CLI. -The CLI will search for service account credentials similarly to the [STACKIT SDK](https://github.com/stackitcloud/stackit-sdk-go) and [Terraform Provider](https://github.com/stackitcloud/terraform-provider-stackit), so if you have setup you environment previously for those tools, you can just run: +The CLI will search for service account credentials similarly to the [STACKIT SDK](https://github.com/stackitcloud/stackit-sdk-go) and [STACKIT Terraform Provider](https://github.com/stackitcloud/terraform-provider-stackit), so if you have already set up your environment for those tools, you can just run: ```bash $ stackit auth activate-service-account @@ -15,7 +15,7 @@ You can also configure the service account credentials directly in the CLI. To g ### Overview -If you dont have a service account, create one in the STACKIT Portal an assign it the necessary permissions, e.g. `owner`. There are two ways to authenticate: +If you don't have a service account, create one in the [STACKIT Portal](https://portal.stackit.cloud/) and assign the necessary permissions to it, e.g. `owner`. There are two ways to authenticate: - Key flow (recommended) - Token flow @@ -39,20 +39,20 @@ When setting up authentication, the CLI will always try to use the key flow firs ### Key flow - The following instructions assume that you have created a service account and assigned it the necessary permissions, e.g. `owner`. + The following instructions assume that you have created a service account and assigned the necessary permissions to it, e.g. `owner`. To use the key flow, you need to have a service account key, which must have an RSA key-pair attached to it. When creating the service account key, a new RSA key-pair can be created automatically, which will be included in the service account key. This will make it much easier to configure the key flow authentication in the CLI, by just providing the service account key. -**Optionally**, you can provide your own private key when creating the service account key, which will then require you to also provide it explicitly to the CLI, additionaly to the service account key. Check the STACKIT Knowledge Base for an [example of how to create your own key-pair](https://docs.stackit.cloud/stackit/en/usage-of-the-service-account-keys-in-stackit-175112464.html#UsageoftheserviceaccountkeysinSTACKIT-CreatinganRSAkey-pair). +**Optionally**, you can provide your own private key when creating the service account key, which will then require you to also provide it explicitly to the CLI, additionally to the service account key. Check the STACKIT Knowledge Base for an [example of how to create your own key-pair](https://docs.stackit.cloud/stackit/en/usage-of-the-service-account-keys-in-stackit-175112464.html#UsageoftheserviceaccountkeysinSTACKIT-CreatinganRSAkey-pair). To configure the key flow, follow this steps: 1. Create a service account key: - In the CLI, run `stackit service-account key create --email ` -- As an alternative, use the STACKIT Portal: go to the `Service Accounts` tab, choose a `Service Account` and go to `Service Account Keys` to create a key. For more details, see [Create a service account key](https://docs.stackit.cloud/stackit/en/create-a-service-account-key-175112456.html) +- As an alternative, use the [STACKIT Portal](https://portal.stackit.cloud/): go to the `Service Accounts` tab, choose a `Service Account` and go to `Service Account Keys` to create a key. For more details, see [Create a service account key](https://docs.stackit.cloud/stackit/en/create-a-service-account-key-175112456.html) 2. Save the content of the service account key by copying it and saving it in a JSON file. diff --git a/AUTOCOMPLETION.md b/AUTOCOMPLETION.md index 011723b91..db6c04a49 100644 --- a/AUTOCOMPLETION.md +++ b/AUTOCOMPLETION.md @@ -42,7 +42,7 @@ stackit completion zsh > "${fpath[1]}/_stackit" stackit completion zsh > $(brew --prefix)/share/zsh/site-functions/_stackit ``` -Additionaly, you might also need to run: +Additionally, you might also need to run: ```shell source $(brew --prefix)/share/zsh/site-functions/_stackit >> ~/.zshrc diff --git a/CONTRIBUTION.md b/CONTRIBUTION.md index 1e419364d..9c8488a9a 100644 --- a/CONTRIBUTION.md +++ b/CONTRIBUTION.md @@ -38,16 +38,16 @@ The CLI commands are located under `internal/cmd`, where each folder includes th ### Implementing a new command -Let's suppose you want to want to implement a new command `bar`, that would be the direct child of an existing command `stackit foo` (meaning it would be invoked as `stackit foo bar`): +Let's suppose you want to implement a new command `bar`, that would be the direct child of an existing command `stackit foo` (meaning it would be invoked as `stackit foo bar`): 1. You would start by creating a new folder `bar/` inside `internal/cmd/foo/` 2. Following with the creation of a file `bar.go` inside your new folder `internal/cmd/foo/bar/` 1. The Go package should be similar to the command usage, in this case `package bar` would be an adequate name - 2. Please refer to the [Command file structure](./CONTRIBUTION.md/#command-file-structure) section for details on the strcutre of the file itself + 2. Please refer to the [Command file structure](./CONTRIBUTION.md/#command-file-structure) section for details on the structure of the file itself 3. To register the command `bar` as a child of the existing command `foo`, add `cmd.AddCommand(bar.NewCmd(p))` to the `addSubcommands` method of the constructor of the `foo` command 1. In this case, `p` is the `printer` that is passed from the root command to all subcommands of the tree (refer to the [Outputs, prints and debug logs](./CONTRIBUTION.md/#outputs-prints-and-debug-logs) section for more details regarding the `printer`) -Please remeber to run `make generate-docs` after your changes to keep the commands' documentation updated. +Please remember to run `make generate-docs` after your changes to keep the commands' documentation updated. #### Command file structure @@ -212,7 +212,7 @@ If you want to add a command that uses a STACKIT service `foo` that was not yet 1. Add a `FooCustomEndpointKey` key in `internal/pkg/config/config.go` (and add it to `ConfigKeys` and set the to default to `""` using `viper.SetDefault`) 2. Update the `stackit config unset` and `stackit config unset` commands by adding flags to set and unset a custom endpoint for the `foo` service API, respectively, and update their unit tests -3. Setup the SDK client configuration, using the authentication method configured in the CLI +3. Set up the SDK client configuration, using the authentication method configured in the CLI 1. This is done in `internal/pkg/services/foo/client/client.go` 2. Below is an example of a typical `client.go` file structure: @@ -291,6 +291,6 @@ If you would like to report a bug, please open a [GitHub issue](https://github.c To ensure we can provide the best support to your issue, follow these guidelines: 1. Go through the existing issues to check if your issue has already been reported. -2. Make sure you are using the latest version of the provider, we will not provide bug fixes for older versions. Also, latest versions may have the fix for your bug. -3. Please provide as much information as you can about your environment, e.g. your version of Go, your version of the provider, which operating system you are using and the corresponding version. +2. Make sure you are using the latest version of the STACKIT CLI, we will not provide bug fixes for older versions. Also, latest versions may have the fix for your bug. +3. Please provide as much information as you can about your environment, e.g. your version of Go, your version of the CLI, which operating system you are using and the corresponding version. 4. Include in your issue the steps to reproduce it, along with code snippets and/or information about your specific use case. This will make the support process much easier and efficient. diff --git a/README.md b/README.md index a9b50a724..da0ca88d6 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ Examples: - `stackit mongodbflex instance create --name my-instance --cpu 1 --ram 4 --acl 0.0.0.0/0 --assume-yes` - `stackit dns zone delete my-zone` -Some commands are implemented at the root, group or sub-group level: +Some commands are implemented at the root, group or subgroup level: - `stackit config` to define variables to be used in future commands. - `stackit ske enable` to enable the SKE engine on your project. @@ -71,9 +71,9 @@ Below you can find a list of the STACKIT services already available in the CLI ( ## Authentication -Most of the commands will require you to be authenticated. Currently it's possible to authenticate with your personal user or with a service account. +Most of the commands will require you to be authenticated. Currently, it's possible to authenticate with your personal user or with a service account. -After successful authentication, the CLI stores credentials in your OS keychain. You won't need to login again for the duration of your session, which is 2h by default but configurable by providing the `--session-time-limit` flag on the `config set` command (see [Configuration](#configuration)). +After successful authentication, the CLI stores credentials in your OS keychain. You won't need to log in again for the duration of your session, which is 2h by default but configurable by providing the `--session-time-limit` flag on the `config set` command (see [Configuration](#configuration)). ### Login with a personal user account @@ -91,7 +91,7 @@ To authenticate using a service account, run: stackit auth activate-service-account ``` -For more details on how to setup authentication using a service account, check our [authentication guide](./AUTHENTICATION.md). +For more details on how to set up authentication using a service account, check our [authentication guide](./AUTHENTICATION.md). ## Configuration @@ -119,9 +119,9 @@ To remove it, you can run: stackit config unset --project-id ``` -Run the `config set` command with the flag `--help` to get a list of all of the available configuration options. +Run the `config set` command with the flag `--help` to get a list of all the available configuration options. -You can lookup your current configuration by checking the configuration file or by running: +You can look up your current configuration by checking the configuration file or by running: ```bash stackit config list @@ -131,11 +131,11 @@ You can also edit the configuration file manually. ## Autocompletion -If you wish to setup command autocompletion in your shell for the STACKIT CLI, please refer to our [autocompletion guide](./AUTOCOMPLETION.md). +If you wish to set up command autocompletion in your shell for the STACKIT CLI, please refer to our [autocompletion guide](./AUTOCOMPLETION.md). ## Reporting issues -If you encounter any issues or have suggestions for improvements, please reach out to the Developer Tools team or open a ticket through the [STACKIT Help Center](https://support.stackit.cloud/). +If you encounter any issues or have suggestions for improvements, please open an issue in the [repository](https://github.com/stackitcloud/stackit-cli/issues). ## Contribute @@ -144,3 +144,13 @@ Your contribution is welcome! For more details on how to contribute, refer to ou ## License Apache 2.0 + + +## Useful Links +- [STACKIT Portal](https://portal.stackit.cloud/) + +- [STACKIT](https://www.stackit.de/en/) + +- [STACKIT Knowledge Base](https://docs.stackit.cloud/stackit/en/knowledge-base-85301704.html) + +- [STACKIT Terraform Provider](https://registry.terraform.io/providers/stackitcloud/stackit/latest/docs) \ No newline at end of file