replicated cli profile and .replicated docs #3611
Conversation
✅ Deploy Preview for replicated-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for replicated-docs-upgrade ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
NoaheCampbell
added
type::feature
type::docs
replicated-ci
added
type::docs
There was a problem hiding this comment.
@NoaheCampbell thanks for your patience with this! I made a handful of edits:
- Moved the info on profiles into the existing Installing the Replicated CLI topic, where we already had info about env vars and replicated login. As is, we can't add it as a separate topic in the Replicated CLI sidebar category because that sidebar category gets automatically rewritten each time the CLI docs are generated. Additionally, seemed like it was probably well enough covered as a section in that existing doc versus adding a new page
- For the same reason, also moved the .replicated stuff to its own sidebar category
- Removed/condensed content from the original PR. I noticed some info that was repeated, and also some details that didn't seem needed (eg, the troubleshooting content). But lmk if you disagree with any of these removals
- Split up the .replicated info into two pages (how-to/concepts and a reference) since it was quite large
- Made some updates to the existing Replicated CLI authentication info in the Installing the Replicated CLI page (there were some details that were no longer accurate after the addition of the replicated profiles option. more details in the comments below)
- Other similar changes
I've also added a few questions for you in the comments where I think the technical details could be made a little more clear. Would you take a look and see what you think?
thanks again, and do lmk if you'd want to talk through any of this! happy to zoom
| For more information about the `docker run` command, see [docker run](https://docs.docker.com/engine/reference/commandline/run/) in the Docker documentation. | ||
| :::note | ||
| Installing in Docker environments requires that you set the `REPLICATED_API_TOKEN` environment variable to authorize the Replicated CLI with an API token. For more information, see [Set Environment Variables](/reference/replicated-cli-installing#env-var). | ||
| ::: |
There was a problem hiding this comment.
Installing in Docker environments requires that you set the
REPLICATED_API_TOKENenvironment variable to authorize the Replicated CLI with an API token. For more information, see Set Environment Variables.
@NoaheCampbell Is this still accurate? As in, is using a replicated profile for auth not supported for Docker?
|
|
||
| ## Overview | ||
|
|
||
| You can add a `.replicated` configuration file to set various preferences for the Replicated CLI, such as the application slug, the channel ID for promoting releases, paths to your application resources (including Helm charts, preflight specs, or Kubernetes manifests), and more. This file enables commands like [`replicated release create`](/reference/replicated-cli-release-create) and [`replicated release lint`](/reference/replicated-cli-release-lint) to automatically discover your application resources and preferences to help ensure consistent builds when managing releases from the Replicated CLI. |
There was a problem hiding this comment.
| You can add a `.replicated` configuration file to set various preferences for the Replicated CLI, such as the application slug, the channel ID for promoting releases, paths to your application resources (including Helm charts, preflight specs, or Kubernetes manifests), and more. This file enables commands like [`replicated release create`](/reference/replicated-cli-release-create) and [`replicated release lint`](/reference/replicated-cli-release-lint) to automatically discover your application resources and preferences to help ensure consistent builds when managing releases from the Replicated CLI. | |
| You can add a `.replicated` configuration file to set various preferences for the Replicated CLI, such as the application slug, the channel ID for promoting releases, paths to your application resources (including Helm charts, preflight specs, or Kubernetes manifests), and more. This file enables the [`replicated release create`](/reference/replicated-cli-release-create) and [`replicated release lint`](/reference/replicated-cli-release-lint) commands to automatically discover your application resources and preferences to help ensure consistent builds when managing releases from the Replicated CLI. |
@NoaheCampbell Is it more accurate to list these commands specifically (see suggested change), rather than saying "commands like...". It wasn't clear to me if there were other commands that use the config file
| - Automatically searches for Helm charts in the current directory | ||
| - Auto-detects preflight specs (files with `kind: Preflight`) | ||
| - Auto-detects support bundle specs (files with `kind: SupportBundle`) | ||
| - Uses default linting configuration |
There was a problem hiding this comment.
@NoaheCampbell is the auto-detection/auto searching described here any different from the current state of things? I wasn't sure what it meant that the CLI automatically searches for Helm charts or auto detects preflight specs. Which commands use this auto detection functionality and for what purpose?
|
|
||
| ```bash | ||
| replicated config init | ||
| ``` |
There was a problem hiding this comment.
^ do you need to run this from a particular directory? Maybe from the root for single project repos or from the directory for monorepos?
| ```bash | ||
| replicated config init | ||
| ``` | ||
| The `replicated config init` command automatically detects Helm charts, preflight specs, and support bundles in your project. |
There was a problem hiding this comment.
and support bundles
@NoaheCampbell How are support bundles used? I didn't see any fields in the .replicated file reference for setting support bundle preferences.
| The Replicated CLI determines which credentials to use for authentication in the following order: | ||
|
|
||
| 1. `REPLICATED_API_TOKEN` environment variable. Environment variables take precedence, allowing temporary overrides without modifying stored profiles. | ||
| 2. Replicated profile passed with the `--profile` flag. This allows for a per-command override of the default Replicated profile. |
There was a problem hiding this comment.
Replicated profile passed with the
--profileflag. This allows for a per-command override of the default Replicated profile.
just a note that the --profile stuff is minimally doc'd as part of this PR. This should be at least documented in the CLI help text for each command that supports it
|
|
||
| The Replicated CLI supports multiple authentication profiles, allowing you to manage and switch between different API credentials. This is useful when working with multiple Replicated accounts or environments. | ||
|
|
||
| Authentication profiles store your API token and can also optionally store custom API endpoints. Profiles are stored securely in `~/.replicated/config.yaml` with file permissions 600 (owner read/write only). Tokens are masked when prompted interactively from the CLI. |
There was a problem hiding this comment.
| Authentication profiles store your API token and can also optionally store custom API endpoints. Profiles are stored securely in `~/.replicated/config.yaml` with file permissions 600 (owner read/write only). Tokens are masked when prompted interactively from the CLI. | |
| Authentication profiles store your API token and can also optionally store custom API endpoints. Profiles are stored securely in `~/.replicated/config.yaml` with file permissions 600 (owner read/write only). |
@NoaheCampbell does this mean if you run replicated profile add without the --token flag, you'll be prompted to provide your token? Do you think this could remain undocumented as it should be apparent to users when they paste their token into the prompt that it's masked, or better to include it? I'll defer to your judgement
| -h, --help help for lint | ||
| -o, --output string The output format to use. One of: json|table (default "table") | ||
| --yaml-dir yaml The directory containing multiple yamls for a Kots release. Cannot be used with the yaml flag. | ||
| --verbose Show verbose output, including discovered images |
There was a problem hiding this comment.
@NoaheCampbell I'm ok if you want to add this in as part of this PR, but note that it's going to be overwritten when we updated the CLI help text and auto generate these CLI docs
| Lint a directory of KOTS manifests | ||
| Lint a directory of KOTS manifests. | ||
|
|
||
| For more information about configuring automatic resource discovery, see [.replicated Configuration File](/reference/cli-replicated-config). |
There was a problem hiding this comment.
| For more information about configuring automatic resource discovery, see [.replicated Configuration File](/reference/cli-replicated-config). | |
| For information about setting linting preferences for your project, see [Add a .replicated File](/reference/replicated-cli-config-file). |
@NoaheCampbell If you'd still like to make these CLI docs updates (see comment on this below), this suggestion updates the link to the new filename
| 'reference/replicated-cli-config-file', | ||
| 'reference/replicated-cli-config-file-reference', | ||
| ], | ||
| }, |
There was a problem hiding this comment.
note: we can't manually add file to the Replicated CLI section in this sidebar. It'll get overwritten by the CLI docs automation. Recommend adding these pages to a new category instead
This PR adds documentation regarding the new additions to the replicated CLI regarding profiles and the .replicated config file. It describes how to authenticate via the new profile command and how to easily migrate to it although it is not mandatory to, as well as how to edit, remove, and swap profiles as needed.
It also describes the new .replicated config file and how to specify the layout of the config file and how to make any needed changes to it, such as changing paths to helm charts, preflight checks, and support bundle specs.