Skip to content

Commit 4c9b572

Browse files
youyongsongyouyongsong
committed
feat: add AC CLI documentation and update script
- Add comprehensive AC CLI documentation files to docs/en/ui/cli_tools/ac/ - getting-started.md: installation and first steps guide - configuration.md: shell completion and kubeconfig setup - ac-and-kubectl-usage.md: comparison and usage patterns - managing-cli-profiles.md: profile and session management - extending-with-plugins.md: plugin development guide - developer-command-reference.md: developer command reference - administrator-command-reference.md: admin command reference - Add update-ac-manual script to automate documentation updates - Update package.json with update-ac-manual script - Update .gitignore to exclude local/* directory - Update UI tools index and add violet.mdx placeholder
1 parent 443dee5 commit 4c9b572

13 files changed

+3189
-4
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
**/node_modules
22
**/dist
3+
local/*
34
.yarn/*
45
!.yarn/patches
56
!.yarn/plugins

‎docs/en/ui/cli_tools/ac/ac-and-kubectl-usage.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
weight: 30
3+
---
4+
5+
# Usage of ac and kubectl Commands
6+
7+
The Kubernetes command-line interface (CLI), kubectl, can be used to run commands against a Kubernetes cluster. Because ACP is a Kubernetes-compatible platform, you can use the supported kubectl binaries that ship with ACP CLI, or you can gain extended functionality by using the ac binary.
8+
9+
## The ac Binary
10+
11+
The ac binary offers the same capabilities as the kubectl binary, but extends to natively support additional ACP platform features, including:
12+
13+
### ACP Platform Integration
14+
15+
ACP CLI provides built-in support for ACP's centralized, proxy-based multi-cluster architecture:
16+
17+
- **Platform Authentication** - Built-in login command for secure authentication with ACP platforms
18+
- **Session Management** - Multi-platform session management with commands like `ac login`, `ac config use-session`, and `ac logout`
19+
- **Enhanced Configuration** - Additional commands like `ac config use-cluster` that make it easier to work with ACP multi-cluster environments
20+
21+
### Intelligent Resource Routing
22+
23+
ACP CLI automatically routes platform-level resource types like `User` and `Project` to the global cluster, since these resources only exist at the platform level. This allows you to access them from any cluster context without manual switching. All other resources work normally with your current cluster context.
24+
25+
#### Resource Routing Example
26+
27+
```bash
28+
# Current context points to workload cluster
29+
$ ac config current-context
30+
prod/workload-a
31+
32+
# User requests global resource - ACP CLI automatically routes to global cluster
33+
$ ac get projects
34+
(i) Note: Targeting global cluster for this command only, as 'projects' is a global resource.
35+
NAME STATUS AGE
36+
project-a Active 32d
37+
project-b Active 18d
38+
39+
# User requests workload resource - operates on current cluster
40+
$ ac get pods
41+
NAME READY STATUS RESTARTS AGE
42+
my-app-7d4f8c9b6-xyz123 1/1 Running 0 2h
43+
```
44+
45+
### Additional Commands
46+
47+
ACP CLI includes additional commands that simplify ACP platform workflows:
48+
49+
- `ac login` - Authenticate to ACP platforms and configure multi-cluster access
50+
- `ac logout` - End platform sessions and clean up configuration
51+
- `ac config get-sessions` - List all configured ACP platform sessions
52+
- `ac config use-session <session_name>` - Switch between ACP platforms
53+
- `ac config use-cluster <cluster_name>` - Switch clusters within current session
54+
- `ac namespace` - Enhanced namespace management with platform context display
55+
- `ac config sync` - Synchronize configuration with platform state
56+
57+
## The kubectl Binary
58+
59+
The kubectl binary is provided as a means to support existing workflows and scripts for new ACP CLI users coming from a standard Kubernetes environment, or for those who prefer to use the kubectl CLI. Existing users of kubectl can continue to use the binary to interact with Kubernetes primitives, with no changes required to the ACP platform.
60+
61+
For more information about kubectl, see the [kubectl documentation](https://kubernetes.io/docs/reference/kubectl/).

‎docs/en/ui/cli_tools/ac/administrator-command-reference.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
weight: 70
3+
---
4+
5+
# AC CLI Administrator Command Reference
6+
7+
This reference provides descriptions and example commands for AC CLI administrator commands. You must have cluster-admin or equivalent permissions to use these commands.
8+
9+
For developer commands, see the AC CLI developer command reference.
10+
11+
Run `ac adm -h` to list all administrator commands or run `ac <command> --help` to get additional details for a specific command.
12+
13+
14+
## ac adm
15+
16+
ACP administrative tools for cluster management
17+
18+
### Example usage
19+
20+
```
21+
# Drain a node for maintenance
22+
ac adm drain NODE_NAME
23+
24+
# Cordon a node (mark as unschedulable)
25+
ac adm cordon NODE_NAME
26+
27+
# Uncordon a node (mark as schedulable)
28+
ac adm uncordon NODE_NAME
29+
```
30+
31+
## ac adm certificate
32+
33+
Modify certificate resources
34+
35+
## ac adm certificate approve
36+
37+
Approve a certificate signing request
38+
39+
### Example usage
40+
41+
```
42+
# Approve CSR 'csr-sqgzp'
43+
ac adm certificate approve csr-sqgzp
44+
```
45+
46+
## ac adm certificate deny
47+
48+
Deny a certificate signing request
49+
50+
### Example usage
51+
52+
```
53+
# Deny CSR 'csr-sqgzp'
54+
ac adm certificate deny csr-sqgzp
55+
```
56+
57+
## ac adm cordon
58+
59+
Mark node as unschedulable
60+
61+
### Example usage
62+
63+
```
64+
# Mark node "foo" as unschedulable
65+
ac adm cordon foo
66+
```
67+
68+
## ac adm drain
69+
70+
Drain node in preparation for maintenance
71+
72+
### Example usage
73+
74+
```
75+
# Drain node "foo", even if there are pods not managed by a replication controller, replica set, job, daemon set, or stateful set on it
76+
ac adm drain foo --force
77+
78+
# As above, but abort if there are pods not managed by a replication controller, replica set, job, daemon set, or stateful set, and use a grace period of 15 minutes
79+
ac adm drain foo --grace-period=900
80+
```
81+
82+
## ac adm taint
83+
84+
Update the taints on one or more nodes
85+
86+
### Example usage
87+
88+
```
89+
# Update node 'foo' with a taint with key 'dedicated' and value 'special-user' and effect 'NoSchedule'
90+
# If a taint with that key and effect already exists, its value is replaced as specified
91+
ac adm taint nodes foo dedicated=special-user:NoSchedule
92+
93+
# Remove from node 'foo' the taint with key 'dedicated' and effect 'NoSchedule' if one exists
94+
ac adm taint nodes foo dedicated:NoSchedule-
95+
96+
# Remove from node 'foo' all the taints with key 'dedicated'
97+
ac adm taint nodes foo dedicated-
98+
99+
# Add a taint with key 'dedicated' on nodes having label myLabel=X
100+
ac adm taint node -l myLabel=X dedicated=foo:PreferNoSchedule
101+
102+
# Add to node 'foo' a taint with key 'bar' and no value
103+
ac adm taint nodes foo bar:NoSchedule
104+
```
105+
106+
## ac adm uncordon
107+
108+
Mark node as schedulable
109+
110+
### Example usage
111+
112+
```
113+
# Mark node "foo" as schedulable
114+
ac adm uncordon foo
115+
```

‎docs/en/ui/cli_tools/ac/configuration.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
weight: 20
3+
---
4+
5+
# Configuring ACP CLI
6+
7+
## Shell Completion
8+
9+
You can enable tab completion for the Bash or Zsh shells.
10+
11+
### Enabling Tab Completion for Bash
12+
13+
After you install ACP CLI (ac), you can enable tab completion to automatically complete ac commands or suggest options when you press Tab. The following procedure enables tab completion for the Bash shell.
14+
15+
#### Prerequisites
16+
17+
- You must have ACP CLI (ac) installed.
18+
- You must have the package bash-completion installed.
19+
20+
#### Procedure
21+
22+
1. Save the Bash completion code to a file:
23+
```bash
24+
$ ac completion bash > ac_bash_completion
25+
```
26+
27+
2. Copy the file to `/etc/bash_completion.d/`:
28+
```bash
29+
$ sudo cp ac_bash_completion /etc/bash_completion.d/
30+
```
31+
32+
You can also save the file to a local directory and source it from your .bashrc file instead.
33+
34+
Tab completion is enabled when you open a new terminal.
35+
36+
### Enabling Tab Completion for Zsh
37+
38+
After you install ACP CLI (ac), you can enable tab completion to automatically complete ac commands or suggest options when you press Tab. The following procedure enables tab completion for the Zsh shell.
39+
40+
#### Prerequisites
41+
42+
You must have ACP CLI (ac) installed.
43+
44+
#### Procedure
45+
46+
To add tab completion for ac to your .zshrc file, run the following command:
47+
48+
```bash
49+
cat >>~/.zshrc<<EOF
50+
autoload -Uz compinit
51+
compinit
52+
if [[ $commands[ac] ]]; then
53+
source <(ac completion zsh)
54+
compdef _ac ac
55+
fi
56+
EOF
57+
```
58+
59+
Tab completion is enabled when you open a new terminal.
60+
61+
## Accessing kubeconfig by using ACP CLI
62+
63+
You can use ACP CLI (ac) to log in to your ACP platform and retrieve a kubeconfig file for accessing clusters from the command line. Unlike traditional single-cluster kubeconfig exports, ac login creates a comprehensive multi-cluster configuration through platform discovery.
64+
65+
### Prerequisites
66+
67+
You have access to an ACP platform endpoint and valid authentication credentials.
68+
69+
### Procedure
70+
71+
1. Log in to your ACP platform by running the following command:
72+
```bash
73+
$ ac login <platform-url> --name <session-name>
74+
```
75+
76+
- `<platform-url>`: The base URL of the ACP platform (e.g., https://acp.prod.example.com)
77+
- `<session-name>`: A user-defined friendly name for this platform connection (e.g., "prod", "staging")
78+
79+
2. The login process automatically:
80+
- Authenticates with the ACP platform
81+
- Discovers all accessible clusters in the platform
82+
- Creates kubeconfig entries for all clusters with ACP-specific metadata
83+
- Sets up a default context pointing to the global cluster
84+
85+
3. To export the configuration to a separate file, run:
86+
```bash
87+
$ ac config view --raw > kubeconfig
88+
```
89+
90+
4. Set the KUBECONFIG environment variable to point to the exported file:
91+
```bash
92+
$ export KUBECONFIG=./kubeconfig
93+
```
94+
95+
5. Use ac to interact with your ACP clusters:
96+
```bash
97+
$ ac get nodes
98+
```
99+
100+
### Multi-Cluster Configuration Handling
101+
102+
ACP CLI login process creates a comprehensive kubeconfig structure that includes:
103+
104+
- **Multiple cluster entries**: One for each accessible cluster in the platform
105+
- **Session metadata**: Platform URL, session name, and cluster descriptions stored in extension fields
106+
- **Unified authentication**: Single user credential entry that works across all clusters in the platform
107+
- **Intelligent naming**: Conflict-free naming conventions using `acp:<session>:<cluster>` format
108+
109+
### Security Considerations
110+
111+
**Important**: The exported kubeconfig file contains authentication tokens that provide access to your ACP platform clusters.
112+
113+
- Store the file securely with appropriate file permissions
114+
- Never commit kubeconfig files to version control systems
115+
- Consider the token expiration and refresh requirements
116+
- Use different session names for different environments (prod, staging, dev) to maintain clear separation
117+
118+
If you plan to reuse the exported kubeconfig file across sessions or machines, ensure it is stored securely and regularly synchronized with `ac config sync` to maintain current cluster lists.

0 commit comments

Comments
 (0)