#Getting Started with ACP CLI

#About ACP CLI

通过 ACP CLI（ac），您可以从终端管理 ACP 平台和集群。ACP CLI 提供类似 kubectl 的体验，针对 ACP 的集中式、基于代理的多集群架构进行了优化。

ACP CLI 适用于以下场景：

• 从统一界面管理 ACP 平台和多个集群
• 直接操作项目源代码，脚本化 ACP 平台操作并自动化工作流
• 在带宽受限且无法使用 Web 控制台时管理项目
• 跨不同 ACP 环境（生产、预发布、开发）管理应用

#Installation

#Installing from Binary

您可以通过下载适用于您操作系统的二进制文件来安装 ACP CLI（ac）。

请按照以下步骤下载正确的软件包：

1. 在浏览器中打开 Alauda Cloud download page。
2. 选择 CLI Tools 进入 CLI 下载页面。
3. 找到 ACP CLI (ac) 部分。
4. 下载与您的操作系统和 CPU 架构匹配的二进制文件（例如，ac-linux-amd64）。

#Installing ACP CLI on Linux

1. 按上述步骤完成下载 Linux 版本二进制文件（例如，ac-linux-amd64 或 ac-linux-arm64）。
2. 赋予二进制文件可执行权限：

   chmod +x ac-linux-amd64
   将 ac-linux-amd64 替换为您下载的文件名。
3. 将二进制文件移动到 PATH 中并重命名为 ac：

   sudo mv ac-linux-amd64 /usr/local/bin/ac
   如果下载了其他版本，请相应调整文件名。
4. 验证安装：

   ac version

#Installing ACP CLI on macOS

1. 按上述步骤完成下载 macOS 版本二进制文件（例如，ac-darwin-amd64 或 ac-darwin-arm64）。
2. 赋予二进制文件可执行权限：

   chmod +x ac-darwin-amd64
   将 ac-darwin-amd64 替换为您下载的文件名。
3. 将二进制文件移动到 PATH 中并重命名为 ac：

   sudo mv ac-darwin-amd64 /usr/local/bin/ac
   如果下载了其他版本，请相应调整文件名。
4. 验证安装：

   ac version

#Installing ACP CLI on Windows

1. 按上述步骤完成下载 Windows 版本二进制文件（例如，ac-windows-amd64.exe）。
2. 将 ac-windows-amd64.exe 移动到 PATH 中的某个目录，并根据需要重命名为 ac.exe。 如果您希望保留原名，也可以，只需确保该文件所在目录在 PATH 中。
3. 验证安装：

   ac version

#First Steps

#Logging into ACP Platform

ac login 命令是连接 ACP 平台的入口。它负责身份验证并自动配置对所有可用集群的访问。

#Interactive Login

为了获得最简单的体验，直接运行 ac login 并按照交互提示操作：

$ ac login
Platform URL: https://prod.acp.com
Session name: prod
Username: user@example.com
Password: [hidden]
✔ Login successful. Welcome, user@example.com!

Your kubeconfig has been configured for the 'prod' platform.
+ Default context 'prod/global' has been created and activated.

To switch clusters within this session, use:
  ac config use-cluster <cluster_name>

To switch between platforms, use:
  ac config get-sessions          # Discover all configured sessions
  ac config use-session <name>    # Switch to different platform

#Login Using Parameters

您也可以直接通过参数登录：

ac login https://prod.acp.com --name prod --username user@example.com

#Login Using Environment Variables

用于自动化和脚本时，可以使用环境变量：

export AC_LOGIN_PLATFORM_URL=https://prod.acp.com
export AC_LOGIN_SESSION=prod
export AC_LOGIN_USERNAME=user@example.com
export AC_LOGIN_PASSWORD=your-password
ac login

#Quick Configuration Management

登录后，ACP CLI 提供便捷命令以支持日常操作：

#View Current Status

使用 ac namespace 查看当前操作上下文：

$ ac namespace
You are currently in namespace "default" (no namespace set in context).

Context:   prod/global
Cluster:   acp:prod:global
Server:    https://acp.prod.example.com/kubernetes/global/

#Switch Clusters

在当前会话中切换集群：

$ ac config use-cluster workload-a
Switched to context "prod/workload-a".

$ ac config use-cluster global
Switched to context "prod/global".

#Switch Namespaces

更改当前命名空间：

$ ac namespace my-app-dev
Now using namespace "my-app-dev" in context "prod/global".

#Basic Resource Operations

使用标准 kubectl 命令管理资源：

# 列出当前命名空间中的 pods
$ ac get pods

# 查看指定 pod 详情
$ ac describe pod my-pod

# 获取所有命名空间的服务
$ ac get services --all-namespaces

# 应用配置文件
$ ac apply -f deployment.yaml

#Managing Multiple Environments

对于管理多个 ACP 平台的用户：

列出所有已配置的会话：

$ ac config get-sessions
CURRENT   SESSION    PLATFORM                              USER                  CLUSTERS
*         prod       https://acp.prod.example.com          user@example.com      3
          staging    https://staging.acp.example.com       user@example.com      2

切换平台：

$ ac config use-session staging
Switched to session "staging".
Context "staging/global" activated.

#Your First Application

让我们创建并查看一个简单的应用以验证环境是否正常：

#Create a Simple Pod

1. 创建一个基础 Pod 配置：

   cat > test-pod.yaml << EOF
   apiVersion: v1
   kind: Pod
   metadata:
     name: test-pod
     labels:
       app: test
   spec:
     containers:
     - name: nginx
       image: nginx:1.20
       ports:
       - containerPort: 80
   EOF

2. 应用该配置：

   $ ac apply -f test-pod.yaml
   pod/test-pod created

#View Application Status

1. 列出 pods 查看应用状态：

   $ ac get pods
   NAME       READY   STATUS    RESTARTS   AGE
   test-pod   1/1     Running   0          30s

2. 查看 pod 详细信息：

   $ ac describe pod test-pod

3. 查看 pod 日志：

   $ ac logs test-pod

#Clean Up

完成后删除测试 pod：

ac delete -f test-pod.yaml

#Getting Help

#Built-in Help System

ACP CLI 提供多层次的全面帮助：

#General Help

获取所有可用命令的概览：

ac help

#Command-Specific Help

获取任意命令的详细帮助：

ac login --help
ac config --help
ac get --help

#Resource Documentation

获取 Kubernetes 资源信息：

ac explain pod
ac explain deployment
ac explain service

#Logging Out

完成工作或需要切换凭据时，使用注销命令：

$ ac logout
✔ Successfully logged out from 'prod' platform.

All session configurations have been removed.
To reconnect, run: ac login https://prod.acp.com --name prod

注销命令将：

• 从本地配置中移除身份验证令牌
• 清理该会话的所有集群和上下文条目
• 撤销 ACP 中当前使用的令牌
• 确保不会留下孤立配置