Skip to content

Commit ba76710

Browse files
qcserestipyqcserestipy
authored
Added docs for config and encryption here from website (#487)
* Added docs for config and encryption here from website Signed-off-by: Patrick Eschenbach <[email protected]> * Added more clear info to encryption docs about ci/cd and production environments Signed-off-by: Patrick Eschenbach <[email protected]> * This index for the harborcli docs also has to live here Signed-off-by: Patrick Eschenbach <[email protected]> --------- Signed-off-by: Patrick Eschenbach <[email protected]>
1 parent ce4b52f commit ba76710

File tree

3 files changed

+203
-0
lines changed

3 files changed

+203
-0
lines changed

‎doc/_index.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: Harbor CLI Documentation
3+
---
4+
5+
Welcome to the Harbor CLI documentation. This provides detailed documentation for the Harbor CLI.
6+
7+
## Harbor CLI Documentation
8+
9+
This section describes the comprehensive set of commands provided by the Harbor CLI, which enables you to efficiently manage and interact with your Harbor registry.
10+
11+
- `harbor` - Configure the Harbor CLI and set global flags to customize your experience.
12+
- `harbor artifact` - Manage artifacts in Harbor Repository
13+
- `harbor project` - Manage projects and assign resources to them
14+
- `harbor registry` - Manage registries in Harbor
15+
- `harbor repo` - Manage repositories in Harbor context
16+
- `harbor user` - Administer users in Harbor, including creating, updating, and managing user accounts
17+
18+
## Access the Documentation Source Files
19+
20+
The source files for this documentation set are located in the [Harbor CLI repository on Github](https://github.com/goharbor/harbor-cli/tree/main/doc/cli-docs).

‎doc/cli-config/_index.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: Harbor CLI Config Management
3+
weight: 25
4+
---
5+
6+
# Harbor CLI Configuration Management
7+
8+
> **Note**
9+
> The Harbor CLI follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) for configuration and data storage by default.
10+
11+
## Introduction
12+
Harbor CLI is a flexible command-line tool that lets you manage various Harbor environments with different credentials. Whether you need a production-ready setup or quick testing configurations, the CLI's hierarchical structure and XDG support help keep things organized.
13+
14+
15+
## Understanding the Configuration Structure
16+
The Harbor CLI can manage multiple credentials and keep track of which credential is currently active. This setup allows you to maintain separate contexts for different Harbor instances or user accounts without having to rewrite configuration files manually. While the Harbor CLI configuration file manages your credentials, passwords themselves are never stored in plain text. Instead, they are secured using the AES-GCM encryption described in the [Harbor CLI Encryption documentation](../cli-config).
17+
18+
### Example Configuration File
19+
Below is a simplified example of a typical Harbor CLI configuration file:
20+
```yaml
21+
current-credential-name: example@demo-harbor
22+
credentials:
23+
- name: example@demo-harbor
24+
username: example-user
25+
password: example-password
26+
serveraddress: https://demo.goharbor.io
27+
```
28+
29+
In this configuration:
30+
- **current-credential-name** references the active credential by name.
31+
- **credentials** holds one or more sets of user credentials, each following the same structure.
32+
33+
## Managing Multiple Credentials
34+
If you need to work with multiple sets of credentials—such as development, staging, or production — Harbor CLI makes it easy to create and switch between them.
35+
36+
> **Note**: For more login command details please refer to the [login command reference](../cli-docs/harbor-login.md).
37+
### Creating a New Credentials Entry
38+
Use the `harbor login` command with the required arguments to store new credentials:
39+
```bash
40+
harbor login --name my-new-credential \
41+
--username myuser \
42+
--password mypass \
43+
https://my-harbor-instance.com
44+
```
45+
This adds a new entry to your credentials list, allowing you to manage different Harbor accounts from the same CLI.
46+
47+
### Switching Between Credentials
48+
To switch to another credential set, run:
49+
```bash
50+
harbor login --name <name-of-credential>
51+
```
52+
The CLI will then set the specified credential as the active one, eliminating the need to manually edit your configuration files. This will overwrite the `current-credential-name`.
53+
54+
55+
## Configuration Hierarchy (Highest to Lowest Priority)
56+
57+
1. **Explicit Config Flag**
58+
Provide a custom config file at runtime using `--config`:
59+
```bash
60+
harbor --config /path/to/custom/config.yaml artifact list
61+
```
62+
63+
2. **Environment Variable**
64+
Set a persistent configuration through the `HARBOR_CLI_CONFIG` environment variable:
65+
```bash
66+
export HARBOR_CLI_CONFIG="$HOME/.custom/harbor-config.yaml"
67+
harbor artifact list # Uses the environment-specified config
68+
```
69+
70+
3. **XDG Default Paths**
71+
Automatically discover configuration in the following order:
72+
```bash
73+
${XDG_CONFIG_HOME}/harbor-cli/config.yaml # If XDG_CONFIG_HOME is set
74+
~/.config/harbor-cli/config.yaml # Fallback default
75+
```
76+
77+
## Data Storage Management
78+
### Data File Location
79+
80+
- **Primary Path**: `$XDG_DATA_HOME/harbor-cli/data.yaml`
81+
- **Fallback Path**: `$HOME/.local/share/harbor-cli/data.yaml`
82+
83+
> **Important**
84+
> The data file automatically tracks the last-used configuration file path
85+
86+
## Configuration Precedence Summary
87+
| Priority | Method | Example |
88+
|----------|----------------------------|---------------------------------------|
89+
| 1 | --config flag | harbor --config ./test.yaml ... |
90+
| 2 | HARBOR_CLI_CONFIG env var | export HARBOR_CLI_CONFIG=... |
91+
| 3 | XDG Default Locations | ~/.config/harbor-cli/config.yaml |
92+
93+
## Practical Usage Examples
94+
### Scenario 1: Temporary Config Override
95+
```bash
96+
harbor --config ./experimental.yaml project create "new-project"
97+
```
98+
99+
### Scenario 2: Persistent Environment-based Config
100+
```bash
101+
echo 'export HARBOR_CLI_CONFIG="$HOME/work/configs/prod-harbor.yaml"' >> ~/.zshrc
102+
source ~/.zshrc
103+
harbor config list # Uses production config
104+
```
105+
106+
### Scenario 3: Reset to Default Configuration
107+
```bash
108+
unset HARBOR_CLI_CONFIG
109+
harbor config delete --current # Deletes current context
110+
```

‎doc/cli-encryption/_index.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: Harbor CLI Encryption
3+
weight: 25
4+
---
5+
6+
# Harbor CLI Encryption Guide
7+
8+
This document provides an overview of how Harbor CLI encrypts sensitive data and offers recommendations for different runtime environments. While the Harbor CLI configuration file manages your credentials, passwords themselves are never stored in plain text. Instead, they are secured using the AES-GCM encryption described below. For details on how to configure and manage these credentials, please refer to the [Harbor CLI Config Management documentation](../cli-config).
9+
10+
## Overview of Encryption
11+
Harbor CLI secures credentials using AES-GCM encryption. An encryption key is automatically generated and stored in one of several keyring backends, depending on your environment:
12+
13+
1. **Environment-based Keyring**
14+
2. **System Keyring**
15+
3. **File-based Keyring (Fallback)**
16+
17+
### How It Works
18+
1. **Key Retrieval**
19+
The CLI checks if an encryption key already exists.
20+
If not present, Harbor CLI generates a new 32-byte key.
21+
2. **Encrypt**
22+
Harbor CLI uses AES-GCM to encrypt credentials with a random nonce.
23+
The CLI stores ciphertext as a Base64-encoded string.
24+
3. **Decrypt**
25+
Harbor CLI decodes and decrypts the stored ciphertext whenever credentials are needed.
26+
27+
## Recommended Backends
28+
### Desktop Environments
29+
**Use the system keyring** if available. This is the most secure method, as most desktop operating systems keep secrets confidentially within their native keyring service.
30+
31+
### Docker, Kubernetes or CI/CD Environments
32+
**Use the environment-based keyring** in production. System keyrings typically aren’t available in containerized environments. Supplying encryption keys as environment variables or secrets is straightforward. In the following subsections we summarize a few examples how to inject the encryption key as environment variables and how to store the secret securely for production environments.
33+
34+
#### Example: Running Harbor CLI in Docker
35+
Use a randomly generated key as an environment variable. This can be generated by tool such as `openssl`:
36+
```bash
37+
docker run -it --rm \
38+
-e HARBOR_ENCRYPTION_KEY="$(openssl rand -base64 32)" \
39+
registry.goharbor.io/harbor-cli/harbor-cli \
40+
login https://demo.goharbor.io -u username -p password
41+
```
42+
43+
#### Example: Running Harbor CLI in Kubernetes
44+
Use a randomly generated key / strong password and store in a kubernetes secret. Pass the secret content as an environment variable to the deployment pod:
45+
```yaml
46+
# secrets.yaml
47+
apiVersion: v1
48+
kind: Secret
49+
metadata:
50+
name: harbor-cli-secrets
51+
type: Opaque
52+
data:
53+
HARBOR_ENCRYPTION_KEY: "<base64-encoded-key>"
54+
55+
# deployment.yaml
56+
spec:
57+
containers:
58+
- name: harbor-cli
59+
image: registry.goharbor.io/harbor-cli/harbor-cli
60+
envFrom:
61+
- secretRef:
62+
name: harbor-cli-secrets
63+
```
64+
65+
#### Example: CI/CD Pipeline
66+
In case you want to use the Harbor CLI in a CI/CD workflow make sure to store your encryption key in a repository secret or similar secret vaults that are provided by your CI/CD provider. In case of GitHub or GitLab the encryption key could be stored in repository secrets and retrieved in either the github actions workflow or GitLab CI pipeline. See the following links for more info on using secrets in [GitHub actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) and [GitLab CI](https://docs.gitlab.com/ci/variables/).
67+
68+
#### Example: Third-Party Secret Vault
69+
Another recommended method to store production encryption secrets are external secret vaults such as AWS Secrets Manager, GCP Secrets Manager, Azure Key Vault or HashiCorp Vault.
70+
71+
### File-based Keyring (Fallback)
72+
73+
In environments where neither a system keyring nor environment-based keyring is available, Harbor CLI can store the encryption key in a file. By default, this file-based keyring is located at `~/.harbor/keyring`. The stored key is protected by file permissions set to allow only the owner to read or write the file. However, **this approach is less secure** and is **not recommended for production**.

0 commit comments

Comments
 (0)