Skip to content

Commit

Permalink
improve doc for configure
Browse files Browse the repository at this point in the history
  • Loading branch information
@JacksonTian @yndu13
JacksonTian authored and yndu13 committed Jul 24, 2024
1 parent adeaf74 commit 973e734
Show file tree
Hide file tree
Showing 4 changed files with 123 additions and 74 deletions.
97 changes: 61 additions & 36 deletions README-CN.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
您也可以在安装 CLI 前在 Cloud Shell 进行试用：

<a href="https://shell.aliyun.com/" target="cloudshell">
<img src="https://img.alicdn.com/tfs/TB1wt1zq9zqK1RjSZFpXXakSXXa-1066-166.png" width="180" />
<img src="https://img.alicdn.com/tfs/TB1wt1zq9zqK1RjSZFpXXakSXXa-1066-166.png" width="180" alt="cloudshell" />
</a>

## 简介
Expand All @@ -27,11 +27,11 @@

如果您在使用 CLI 的过程中遇到任何问题，请直接提交 Issues。

**注意**：阿里云 CLI 使用 OpenAPI 方式访问云产品，确保您已经开通了要使用的云产品并了解该产品的 OpenAPI 的使用。您可以在[阿里云 OpenAPI 开发者门户](https://next.api.aliyun.com/)查看产品 API 文档，了解 API 的使用方式及参数列表。
**注意**：阿里云 CLI 使用 OpenAPI 方式访问云产品，确保您已经开通了要使用的云产品并了解该产品的 OpenAPI 的使用。您可以在[阿里云 OpenAPI 开发者门户](https://api.aliyun.com/)查看产品 API 文档，了解 API 的使用方式及参数列表。

## 使用诊断

[Troubleshoot](https://troubleshoot.api.aliyun.com/?source=github_sdk) 提供 OpenAPI 使用诊断服务，通过 `RequestID` 或 `报错信息` ，帮助开发者快速定位，为开发者提供解决方案。
[Troubleshoot](https://api.aliyun.com/troubleshoot?source=github_sdk) 提供 OpenAPI 使用诊断服务，通过 `RequestID` 或 `报错信息` ，帮助开发者快速定位，为开发者提供解决方案。

## CLI Releases

Expand All @@ -43,7 +43,7 @@ CLI 版本更改说明请参考 [CHANGELOG](./CHANGELOG.md)

阿里云 CLI 工具下载、解压后即可使用，支持 Mac、Linux(amd64/arm64)、Windows 平台(x64版本)。您可以将解压的`aliyun` 可执行文件移至 `/usr/local/bin` 目录下，或添加到 `$PATH` 中。

下载链接如下 (<img src="https://img.shields.io/github/release/aliyun/aliyun-cli.svg" alt="Latest Stable Version" />)：
下载链接如下 (![Latest Stable Version](https://img.shields.io/github/release/aliyun/aliyun-cli.svg))：

- [Mac 图形界面安装器](https://aliyuncli.alicdn.com/aliyun-cli-latest.pkg)
- [Mac Universal](https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-universal.tgz)
Expand All @@ -69,7 +69,7 @@ CLI 版本更改说明请参考 [CHANGELOG](./CHANGELOG.md)

在使用阿里云 CLI 之前，您需要配置调用阿里云资源所需的凭证信息、地域、语言等。

你可以运行 `aliyun configure` 命令进行快速配置
你可以运行 `aliyun configure` 命令进行快速配置：

```sh
$ aliyun configure
Expand All @@ -82,20 +82,47 @@ Default Language [zh|en] en:
Saving profile[akProfile] ...Done.
```

### 其他认证方式
这将会以 AK 的认证模式对 default 进行凭证和其它配置。

阿里云 CLI，可通过在`configure`命令后增加`--mode <authenticationMethod>`参数的方式来使用不同的认证方式，目前支持的认证方式如下：
### 所有凭证模式

| 验证方式 | 说明 |
|------------|-------------------------------------|
| AK | 使用AccessKey ID/Secret访问 |
| StsToken | 使用STS Token访问 |
| RamRoleArn | 使用RAM子账号的AssumeRole方式访问 |
| EcsRamRole | 在ECS实例上通过EcsRamRole实现免密验证 |
可通过在 `configure` 命令后增加 `--mode <authenticationMethod>` 参数的方式来使用不同的凭证方式，目前支持的认证方式如下：

| 凭证模式 | 说明 |
|---------------------|-----------------------------------------|
| AK | 使用直接的 AccessKey ID/Secret 访问凭证 |
| RamRoleArn | 使用 RAM 子账号角色扮演提供访问凭证 |
| EcsRamRole | 使用 ECS 实例角色提供访问凭证 |
| OIDC | 使用 OIDC 角色扮演的方式访问 |
| External | 使用外部进程提供访问凭证 |
| CredentialsURI | 使用外部服务提供访问凭证 |
| ChainableRamRoleArn | 使用链式角色扮演的方式提供访问凭证 |

如果在配置时不传递 `--mode`，将默认使用 AK 模式。

### RAM 子账号角色扮演

您可以使用 `--mode RamRoleArn` 指定通过 RAM 子账号进行角色扮演来获取凭证。它的底层是通过 AssumeRole 方法来换取
临时凭证。示例如下：

```shell
$ aliyun configure --mode RamRoleArn --profile subaccount
Configuring profile 'subaccount' in 'RamRoleArn' authenticate mode...
Access Key Id []: AccessKey ID
Access Key Secret []: AccessKey Secret
Sts Region []: cn-hangzhou
Ram Role Arn []: acs:ram::******:role/ecs-test
Role Session Name []: sessionname
Expired Seconds []: 900
Default Region Id []: cn-hangzhou
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en:
Saving profile[subaccount] ...Done.
```

### 使用外部程序获取凭证

您可以使用 `--mode External` 指定通过外部程序获取凭证数据，CLI 将会以执行该程序命令并其返回作为凭证来发起调用。
您可以使用 `--mode External` 指定通过外部程序获取凭证数据，CLI 将会以执行该程序命令并将其返回作为凭证来使用。

约定：

Expand All @@ -105,7 +132,7 @@ Saving profile[akProfile] ...Done.

关键字段:

- mode: 指定返回凭证类型
- mode: 指定返回凭证类型，目前支持两种静态的凭证。

各凭证返回结构示例:

Expand All @@ -130,27 +157,6 @@ Saving profile[akProfile] ...Done.
}
```

- RamRoleArn

```json
{
"mode": "RamRoleArn",
"access_key_id": "accessKeyId",
"access_key_secret": "accessKeySecret",
"ram_role_arn": "ramRoleArn",
"ram_session_name": "ramSessionName"
}
```

- EcsRamRole

```json
{
"mode": "EcsRamRole",
"ram_role_name": "ramRoleName"
}
```

#### 示例

```shell
Expand All @@ -165,6 +171,8 @@ Saving profile[externalTest] ...Done.

### 使用链式 RamRoleArn

通过 ChainableRamRoleArn ，可以指定一个前置凭证配置，然后再进行角色扮演。前置凭证的设置会更灵活，它可以是子账号的 AK，也可以是通过其它方式换取的 STS，比如 EcsRamRole。

你可以使用 `--mode ChainableRamRoleArn` 来组合源配置和 RamRoleARN 的角色扮演流程。下面的例子从源配置中获取中间凭证，再基于中间凭证完成角色扮演，获取最终的凭证。

```json
Expand Down Expand Up @@ -217,6 +225,23 @@ Saving profile[externalTest] ...Done.

其他情况，CLI 会当作失败案例处理。

### 使用 OIDC 获取凭证

你可以通过 `--mode OIDC` 来使用基于 OIDC 的 SSO 角色扮演获取凭证。示例如下：

```shell
$ aliyun configure --mode OIDC --profile oidc_p
Configuring profile 'oidc_p' in 'OIDC' authenticate mode...
OIDC Provider ARN []: xxxx
OIDC Token File []: xxx
RAM Role ARN []: xxx
Role Session Name []: xxx
Default Region Id []: xxx
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en:
Saving profile[oidc_p] ...Done.
```

### 启用 zsh/bash 自动补全

- 使用 `aliyun auto-completion` 命令开启自动补全，目前支持 zsh/bash
Expand Down
85 changes: 53 additions & 32 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ The Alibaba Cloud CLI is an open source tool, you can get the latest version fro
You can also try it out in the Cloud Shell before installing the CLI.

<a href="https://shell.aliyun.com/" target="cloudshell">
<img src="https://img.alicdn.com/tfs/TB1wt1zq9zqK1RjSZFpXXakSXXa-1066-166.png" width="180" />
<img src="https://img.alicdn.com/tfs/TB1wt1zq9zqK1RjSZFpXXakSXXa-1066-166.png" width="180" alt="cloudshell" />
</a>

## Introduction
Expand All @@ -29,7 +29,7 @@ The Alibaba Cloud CLI is a tool to manage and use Alibaba Cloud resources throug
## Troubleshoot

[Troubleshoot](https://troubleshoot.api.aliyun.com/?source=github_sdk) Provide OpenAPI diagnosis service to help developers locate quickly and provide solutions for developers through `RequestID` or `error message`.
[Troubleshoot](https://api.aliyun.com/troubleshoot?source=github_sdk) Provide OpenAPI diagnosis service to help developers locate quickly and provide solutions for developers through `RequestID` or `error message`.

## CLI Releases

Expand All @@ -41,7 +41,7 @@ The release notes for the CLI can be found in the [CHANGELOG](./CHANGELOG.md)

Download the installer, then extract the installer. You can move the extracted `aliyun` executable file to the `/usr/local/bin` directory or add it to the `$PATH`.

Download link: (<img src="https://img.shields.io/github/release/aliyun/aliyun-cli.svg" alt="Latest Stable Version" />)
Download link: (![Latest Stable Version](https://img.shields.io/github/release/aliyun/aliyun-cli.svg))

- [Mac GUI Installer](https://aliyuncli.alicdn.com/aliyun-cli-latest.pkg)
- [Mac Universal](https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-universal.tgz)
Expand Down Expand Up @@ -70,7 +70,7 @@ If you need detailed installation steps or compile the installation steps, pleas

## Configure

For detailed configuration instructions, please visit the official website [Configuration Alibaba Cloud CLI](https://www.alibabacloud.com/help/doc-detail/110341.htm?spm=a2c63.p38356.b99.12.77d468f5YJVFg1).
For detailed configuration instructions, please visit the official website [Configuration Alibaba Cloud CLI](https://www.alibabacloud.com/help/doc-detail/110341.htm).

Before using Alibaba Cloud CLI to invoke the services, you need to configure the credential information, region, language, etc.

Expand All @@ -92,12 +92,37 @@ You can specify the authentication method to use by using the `configure` comman

The following are supported authentication methods:

| Authentication methods | Description |
| ---------------------- | ------------------------------------------------------------ |
| AK | Use AccessKey ID and Secret to access Alibaba Cloud services |
| StsToken | Use STS token to access Alibaba Cloud services |
| RamRoleArn | Use the AssumeRole to access Alibaba Cloud services |
| EcsRamRole | Use the EcsRamRole to access ECS resources |
| Authentication methods | Description |
|------------------------|-------------------------------------------------------------|
| AK | Use direct AccessKey ID/Secret as access credentials |
| RamRoleArn | Use RAM role assumption to provide access credentials |
| EcsRamRole | Use ECS instance role to provide access credentials |
| OIDC | Use OIDC role assumption to provide access credentials |
| External | Use external processes to provide access credentials |
| CredentialsURI | Use external services to provide access credentials |
| ChainableRamRoleArn | Use chainable role assumption to provide access credentials |

If the --mode is not specified during configuration, the AK mode will be used by default.

### RAM Sub-account Role Assumption

You can specify obtaining credentials through RAM sub-account role assumption by using the --mode RamRoleArn. It works by exchanging temporary
credentials through the AssumeRole method. An example is as follows:

```shell
$ aliyun configure --mode RamRoleArn --profile subaccount
Configuring profile 'subaccount' in 'RamRoleArn' authenticate mode...
Access Key Id []: AccessKey ID
Access Key Secret []: AccessKey Secret
Sts Region []: cn-hangzhou
Ram Role Arn []: acs:ram::******:role/ecs-test
Role Session Name []: sessionname
Expired Seconds []: 900
Default Region Id []: cn-hangzhou
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en:
Saving profile[subaccount] ...Done.
```

### Use an external program to get credentials

Expand All @@ -111,7 +136,7 @@ Agreement：

Key field:

- mode: Specify the type of credentials returned
- mode: Specifies the type of credentials returned, currently supports two types of static credentials.

Example of the return of each credential type:

Expand All @@ -136,27 +161,6 @@ Example of the return of each credential type:
}
```

- RamRoleArn

```json
{
"mode": "RamRoleArn",
"access_key_id": "accessKeyId",
"access_key_secret": "accessKeySecret",
"ram_role_arn": "ramRoleArn",
"ram_session_name": "ramSessionName"
}
```

- EcsRamRole

```json
{
"mode": "EcsRamRole",
"ram_role_name": "ramRoleName"
}
```

#### Example

```shell
Expand Down Expand Up @@ -224,6 +228,23 @@ The Credentials URI must be response with status code 200, and following body:

Otherwise, CLI treate as failure case.

### Use OIDC to get credentials

You can use the `--mode OIDC` to obtain credentials through OIDC-based SSO role assumption. An example is as follows:

```shell
$ aliyun configure --mode OIDC --profile oidc_p
Configuring profile 'oidc_p' in 'OIDC' authenticate mode...
OIDC Provider ARN []: xxxx
OIDC Token File []: xxx
RAM Role ARN []: xxx
Role Session Name []: xxx
Default Region Id []: xxx
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en:
Saving profile[oidc_p] ...Done.
```

### Enable bash/zsh auto completion

- Use `aliyun auto-completion` command to enable auto completion in zsh/bash
Expand Down
2 changes: 1 addition & 1 deletion config/configure.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ func NewConfigureCommand() *cli.Command {
Short: i18n.T(
"configure credential and settings",
"配置身份认证和其他信息"),
Usage: "configure --mode {AK|StsToken|RamRoleArn|EcsRamRole|RsaKeyPair|RamRoleArnWithRoleName|ChainableRamRoleArn} --profile <profileName>",
Usage: "configure --mode {AK|RamRoleArn|EcsRamRole|OIDC|External|CredentialsURI|ChainableRamRoleArn} --profile <profileName>",
Run: func(ctx *cli.Context, args []string) error {
if len(args) > 0 {
return cli.NewInvalidCommandError(args[0], ctx)
Expand Down
13 changes: 8 additions & 5 deletions config/profile.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,14 @@ import (
type AuthenticateMode string

const (
AK = AuthenticateMode("AK")
StsToken = AuthenticateMode("StsToken")
RamRoleArn = AuthenticateMode("RamRoleArn")
EcsRamRole = AuthenticateMode("EcsRamRole")
RsaKeyPair = AuthenticateMode("RsaKeyPair")
AK = AuthenticateMode("AK")
// Deprecated: StsToken is deprecated
StsToken = AuthenticateMode("StsToken")
RamRoleArn = AuthenticateMode("RamRoleArn")
EcsRamRole = AuthenticateMode("EcsRamRole")
// Deprecated: RsaKeyPair is deprecated
RsaKeyPair = AuthenticateMode("RsaKeyPair")
// Deprecated: RamRoleArnWithRoleName is deprecated, use ChainableRamRoleArn instead of
RamRoleArnWithEcs = AuthenticateMode("RamRoleArnWithRoleName")
ChainableRamRoleArn = AuthenticateMode("ChainableRamRoleArn")
External = AuthenticateMode("External")
Expand Down

0 comments on commit 973e734

Please sign in to comment.