管理 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

登录流程：

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

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

# 登出当前平台会话
ac logout

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

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

`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: <TOKEN>
    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）

NOTE

acp: 前缀确保 ACP CLI 管理的条目不会与现有 kubeconfig 条目冲突。用户可以手动重命名这些条目——ACP CLI 通过元数据识别条目，而非名称。

手动配置 CLI 配置文件

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

TIP

大多数用户应使用上述便捷命令。

手动配置命令适用于高级场景：

自定义上下文命名 - 创建不遵循 ACP CLI 命名规范的上下文
非 ACP 环境 - 在 ACP 会话之外管理传统的 kubectl 上下文
复杂多上下文场景 - 需要精确控制上下文的高级工作流
排查配置问题 - 调试或修复配置问题

标准配置命令

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

子命令	用法
`set-cluster`	在 CLI 配置文件中设置集群条目
`set-context`	在 CLI 配置文件中设置上下文条目
`use-context`	使用指定的上下文名称设置当前上下文
`set`	在 CLI 配置文件中设置单个值
`unset`	在 CLI 配置文件中取消设置单个值
`view`	显示当前合并的 CLI 配置

手动操作示例

创建自定义上下文：

# 创建自定义命名的上下文
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 配置文件从您的工作站获取，遵循以下层级和合并规则：
- 如果设置了 --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
对于仍缺失的信息，使用默认值并提示输入额外信息。

#管理 CLI 配置文件

#目录

#便捷的配置管理

#平台和会话管理

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

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

#ac config get-sessions - 列出所有已配置的 ACP 平台会话

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

#日常操作

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

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

#ac config sync - 同步平台配置

#了解 ACP CLI 配置结构

#ACP CLI 增强的 kubeconfig 结构

#元数据结构与组织

#基于元数据的识别

#命名规范

#手动配置 CLI 配置文件

#标准配置命令

#手动操作示例

#加载与合并规则