#管理 CLI 配置文件

CLI 配置文件允许您为 ACP CLI（ac）配置不同的配置文件或上下文。一个上下文由与昵称关联的用户认证信息和 ACP 平台服务器信息组成。

#便捷的配置管理

ACP CLI 提供了增强命令，使配置管理比传统的 kubeconfig 操作更加简单。这些命令设计为与 ACP 的多集群环境无缝协作。

#平台与会话管理

#ac login - 认证并配置对 ACP 平台的访问

ac login 命令是建立与 ACP 平台连接的主要入口。它对用户进行认证，并自动配置所有必要的 kubeconfig 条目。

# 交互式登录 ACP 平台
ac login https://prod.acp.com --name prod

# 指定集群和命名空间登录
ac login https://prod.acp.com --name prod --cluster workload-a --namespace my-app

# 使用环境变量登录（用于自动化）
AC_LOGIN_PLATFORM_URL=https://prod.acp.com AC_LOGIN_SESSION=prod AC_LOGIN_USERNAME=user AC_LOGIN_PASSWORD=secret ac login

登录流程：

1. 对 ACP 平台进行认证
2. 发现平台内所有可访问的集群
3. 在 kubeconfig 中创建集群和用户条目
4. 创建并激活上下文：
   • 如果指定了 --cluster：为该特定集群创建上下文
   • 如果指定了 --namespace：在上下文中设置命名空间
   • 如果未指定集群：默认为 global 集群
   • 上下文名称格式为：<session_name>/<cluster_name>

#ac logout - 结束平台会话并清理配置

# 登出当前平台会话
ac logout

# 登出指定会话
ac logout --session prod

logout 命令会移除所有与会话相关的配置条目，包括集群、用户和上下文。

#ac config get-sessions - 列出所有已配置的 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
          dev        https://dev.acp.example.com           dev-user@example.com  1

该命令显示：

• CURRENT：当前上下文是否属于该会话（用 * 标记）
• SESSION：会话名称（登录时用户定义）
• PLATFORM：基础平台 URL
• USER：会话认证用户名
• CLUSTERS：该会话中可用的集群数量

#ac config use-session <session_name> - 切换 ACP 平台

# 切换到 staging 平台（默认为 global 集群）
ac config use-session staging

# 切换到会话中的特定集群
ac config use-session prod --cluster workload-a

# 指定命名空间切换
ac config use-session staging --cluster workload-b --namespace my-app

该命令根据您的会话和集群需求智能选择或创建合适的上下文。

#日常操作

#ac config use-cluster <cluster_name> - 在当前会话内切换集群

# 切换到当前会话中的 workload 集群
ac config use-cluster workload-a

# 创建带特定命名空间的新上下文
ac config use-cluster workload-b --namespace my-app

该命令在当前平台会话中查找或创建指定集群的上下文。

#ac namespace - 查看当前状态并切换命名空间

查看当前状态：

ac namespace

示例输出：

You are currently in namespace "my-app-dev".

Context:   prod/workload-a
Cluster:   acp:prod:workload-a
Server:    https://acp.prod.example.com/kubernetes/workload-a/
Platform:  https://acp.prod.example.com/
Session:   prod

切换命名空间：

ac namespace my-app-dev

#ac config sync - 同步平台配置

# 同步当前平台会话
ac config sync

# 同步指定会话
ac config sync --session prod

# 同步所有会话
ac config sync --all

sync 命令会从 ACP 平台刷新您的配置，添加新集群并根据需要更新凭证。

#了解 ACP CLI 配置结构

ACP CLI 将所有配置信息存储在标准的 ~/.kube/config 文件中，确保与 kubectl 及其他 Kubernetes 工具完全兼容，同时增加了 ACP 特有的增强功能。

#ACP CLI 增强的 kubeconfig 结构

ACP CLI 在标准 kubeconfig 格式基础上扩展了 ACP 特定的元数据，以增强平台集成：

apiVersion: v1
clusters:
- cluster:
    server: https://acp.prod.example.com/kubernetes/global/
    extensions:
    - name: acp.io/v1
      extension:
        isGlobal: true
        platformUrl: https://acp.prod.example.com
        sessionName: prod
        clusterName: global
        description: global cluster
        note: This cluster item is managed by ac CLI, to avoid unexpected behavior, do not edit this item.
  name: acp:prod:global
- cluster:
    server: https://acp.prod.example.com/kubernetes/workload-a/
    extensions:
    - name: acp.io/v1
      extension:
        isGlobal: false
        platformUrl: https://acp.prod.example.com
        sessionName: prod
        clusterName: workload-a
        description: business cluster for team alpha
        note: This cluster item is managed by ac CLI, to avoid unexpected behavior, do not edit this item.
  name: acp:prod:workload-a
contexts:
- context:
    cluster: acp:prod:global
    namespace: default
    user: acp:prod:user
  name: prod/global
- context:
    cluster: acp:prod:workload-a
    namespace: my-app
    user: acp:prod:user
  name: prod/workload-a
current-context: prod/global
kind: Config
preferences: {}
users:
- name: acp:prod:user
  user:
    token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    extensions:
    - name: acp.io/v1
      extension:
        platformUrl: https://acp.prod.example.com
        sessionName: prod
        username: user@example.com
        note: This user item is managed by ac CLI, to avoid unexpected behavior, do not edit this item.

#元数据结构与组织

ACP CLI 使用扩展元数据来组织和识别配置条目：

#基于元数据的识别

• 平台识别：使用 platformUrl 识别所属平台
• 会话关联：使用 sessionName 将相关集群、用户和上下文分组
• global 集群检测：使用 isGlobal 字段识别管理集群
• 用户凭证定位：在用户扩展中匹配 sessionName 和 platformUrl

#命名规范

ACP CLI 创建新条目时采用统一命名规范：

• 集群条目：acp:<session_name>:<cluster_name>（例如 acp:prod:global）
• 用户条目：acp:<session_name>:user（例如 acp:prod:user）
• 上下文条目：<session_name>/<cluster_name>（例如 prod/global）

#手动配置 CLI 配置文件

对于需要精确控制配置的高级用户，ACP CLI 支持所有标准的 kubectl config 命令以进行手动 kubeconfig 管理。

#标准配置命令

ACP CLI 完全兼容 kubectl config 子命令：

#手动操作示例

创建自定义上下文：

# 创建自定义命名的上下文
ac config set-context my-custom-context --cluster=acp:prod:workload-a --namespace=my-app

# 切换到自定义上下文
ac config use-context my-custom-context

查看当前配置：

# 显示合并后的配置
ac config view

# 显示指定文件的配置
ac config view --config=/path/to/config

更新上下文命名空间：

# 设置当前上下文的命名空间
ac config set-context `ac config current-context` --namespace=my-namespace

#加载与合并规则

在执行 CLI 操作时，您可以遵循以下规则来确定 CLI 配置的加载和合并顺序：

• CLI 配置文件从您的工作站加载，遵循以下层级和合并规则：

  • 如果设置了 --config 选项，则仅加载该文件。该标志只设置一次，不进行合并。
  • 如果设置了 $KUBECONFIG 环境变量，则使用该变量。该变量可以是路径列表，路径会被合并。当某个值被修改时，修改发生在定义该段的文件中。创建新值时，创建于第一个存在的文件中。如果链中无文件存在，则创建列表中的最后一个文件。
  • 否则，使用 ~/.kube/config 文件，不进行合并。

• 使用的上下文根据以下流程中第一个匹配项确定：

  • --context 选项的值
  • CLI 配置文件中的 current-context 值
  • 此阶段允许为空值

• 使用的用户和集群确定。此时您可能有或没有上下文；它们基于以下流程中第一个匹配项构建，分别运行一次用于用户和集群：

  • 用户名的 --user 选项和集群名的 --cluster 选项
  • 如果存在 --context 选项，则使用该上下文的值
  • 此阶段允许为空值

• 实际使用的集群信息确定。此时您可能有或没有集群信息。集群信息的每个部分基于以下流程中第一个匹配项构建：

  • 以下命令行选项的值：--server、--api-version、--certificate-authority、--insecure-skip-tls-verify
  • 如果集群信息中存在该属性值，则使用它
  • 如果没有服务器地址，则报错

• 实际使用的用户信息确定。用户构建规则与集群相同，但每个用户只能有一种认证方式；认证方式冲突会导致操作失败。命令行选项优先于配置文件值。有效的命令行选项包括：

  • --auth-path
  • --client-certificate
  • --client-key
  • --token

• 对于仍缺失的信息，使用默认值并提示输入额外信息。