Skip to content

Commit 973e734

Browse files
JacksonTianyndu13
JacksonTian
authored and
yndu13
committed
improve doc for configure
1 parent adeaf74 commit 973e734

File tree

4 files changed

+123
-74
lines changed

4 files changed

+123
-74
lines changed

‎README-CN.md

+61-36
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
您也可以在安装 CLI 前在 Cloud Shell 进行试用：
1919

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

2424
## 简介
@@ -27,11 +27,11 @@
2727

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

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

3232
## 使用诊断
3333

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

3636
## CLI Releases
3737

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

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

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

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

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

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

7474
```sh
7575
$ aliyun configure
@@ -82,20 +82,47 @@ Default Language [zh|en] en:
8282
Saving profile[akProfile] ...Done.
8383
```
8484

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

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

89-
| 验证方式 | 说明 |
90-
|------------|-------------------------------------|
91-
| AK | 使用AccessKey ID/Secret访问 |
92-
| StsToken | 使用STS Token访问 |
93-
| RamRoleArn | 使用RAM子账号的AssumeRole方式访问 |
94-
| EcsRamRole | 在ECS实例上通过EcsRamRole实现免密验证 |
89+
可通过在 `configure` 命令后增加 `--mode <authenticationMethod>` 参数的方式来使用不同的凭证方式，目前支持的认证方式如下：
90+
91+
| 凭证模式 | 说明 |
92+
|---------------------|-----------------------------------------|
93+
| AK | 使用直接的 AccessKey ID/Secret 访问凭证 |
94+
| RamRoleArn | 使用 RAM 子账号角色扮演提供访问凭证 |
95+
| EcsRamRole | 使用 ECS 实例角色提供访问凭证 |
96+
| OIDC | 使用 OIDC 角色扮演的方式访问 |
97+
| External | 使用外部进程提供访问凭证 |
98+
| CredentialsURI | 使用外部服务提供访问凭证 |
99+
| ChainableRamRoleArn | 使用链式角色扮演的方式提供访问凭证 |
100+
101+
如果在配置时不传递 `--mode`，将默认使用 AK 模式。
102+
103+
### RAM 子账号角色扮演
104+
105+
您可以使用 `--mode RamRoleArn` 指定通过 RAM 子账号进行角色扮演来获取凭证。它的底层是通过 AssumeRole 方法来换取
106+
临时凭证。示例如下：
107+
108+
```shell
109+
$ aliyun configure --mode RamRoleArn --profile subaccount
110+
Configuring profile 'subaccount' in 'RamRoleArn' authenticate mode...
111+
Access Key Id []: AccessKey ID
112+
Access Key Secret []: AccessKey Secret
113+
Sts Region []: cn-hangzhou
114+
Ram Role Arn []: acs:ram::******:role/ecs-test
115+
Role Session Name []: sessionname
116+
Expired Seconds []: 900
117+
Default Region Id []: cn-hangzhou
118+
Default Output Format [json]: json (Only support json)
119+
Default Language [zh|en] en:
120+
Saving profile[subaccount] ...Done.
121+
```
95122

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

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

100127
约定：
101128

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

106133
关键字段:
107134

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

110137
各凭证返回结构示例:
111138

@@ -130,27 +157,6 @@ Saving profile[akProfile] ...Done.
130157
}
131158
```
132159

133-
- RamRoleArn
134-
135-
```json
136-
{
137-
"mode": "RamRoleArn",
138-
"access_key_id": "accessKeyId",
139-
"access_key_secret": "accessKeySecret",
140-
"ram_role_arn": "ramRoleArn",
141-
"ram_session_name": "ramSessionName"
142-
}
143-
```
144-
145-
- EcsRamRole
146-
147-
```json
148-
{
149-
"mode": "EcsRamRole",
150-
"ram_role_name": "ramRoleName"
151-
}
152-
```
153-
154160
#### 示例
155161

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

166172
### 使用链式 RamRoleArn
167173

174+
通过 ChainableRamRoleArn ，可以指定一个前置凭证配置，然后再进行角色扮演。前置凭证的设置会更灵活，它可以是子账号的 AK，也可以是通过其它方式换取的 STS，比如 EcsRamRole。
175+
168176
你可以使用 `--mode ChainableRamRoleArn` 来组合源配置和 RamRoleARN 的角色扮演流程。下面的例子从源配置中获取中间凭证，再基于中间凭证完成角色扮演，获取最终的凭证。
169177

170178
```json
@@ -217,6 +225,23 @@ Saving profile[externalTest] ...Done.
217225

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

228+
### 使用 OIDC 获取凭证
229+
230+
你可以通过 `--mode OIDC` 来使用基于 OIDC 的 SSO 角色扮演获取凭证。示例如下：
231+
232+
```shell
233+
$ aliyun configure --mode OIDC --profile oidc_p
234+
Configuring profile 'oidc_p' in 'OIDC' authenticate mode...
235+
OIDC Provider ARN []: xxxx
236+
OIDC Token File []: xxx
237+
RAM Role ARN []: xxx
238+
Role Session Name []: xxx
239+
Default Region Id []: xxx
240+
Default Output Format [json]: json (Only support json)
241+
Default Language [zh|en] en:
242+
Saving profile[oidc_p] ...Done.
243+
```
244+
220245
### 启用 zsh/bash 自动补全
221246

222247
- 使用 `aliyun auto-completion` 命令开启自动补全，目前支持 zsh/bash

‎README.md

+53-32
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ The Alibaba Cloud CLI is an open source tool, you can get the latest version fro
1818
You can also try it out in the Cloud Shell before installing the CLI.
1919

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

2424
## Introduction
@@ -29,7 +29,7 @@ The Alibaba Cloud CLI is a tool to manage and use Alibaba Cloud resources throug
2929
3030
## Troubleshoot
3131

32-
[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`.
32+
[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`.
3333

3434
## CLI Releases
3535

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

4242
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`.
4343

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

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

7171
## Configure
7272

73-
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).
73+
For detailed configuration instructions, please visit the official website [Configuration Alibaba Cloud CLI](https://www.alibabacloud.com/help/doc-detail/110341.htm).
7474

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

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

9393
The following are supported authentication methods:
9494

95-
| Authentication methods | Description |
96-
| ---------------------- | ------------------------------------------------------------ |
97-
| AK | Use AccessKey ID and Secret to access Alibaba Cloud services |
98-
| StsToken | Use STS token to access Alibaba Cloud services |
99-
| RamRoleArn | Use the AssumeRole to access Alibaba Cloud services |
100-
| EcsRamRole | Use the EcsRamRole to access ECS resources |
95+
| Authentication methods | Description |
96+
|------------------------|-------------------------------------------------------------|
97+
| AK | Use direct AccessKey ID/Secret as access credentials |
98+
| RamRoleArn | Use RAM role assumption to provide access credentials |
99+
| EcsRamRole | Use ECS instance role to provide access credentials |
100+
| OIDC | Use OIDC role assumption to provide access credentials |
101+
| External | Use external processes to provide access credentials |
102+
| CredentialsURI | Use external services to provide access credentials |
103+
| ChainableRamRoleArn | Use chainable role assumption to provide access credentials |
104+
105+
If the --mode is not specified during configuration, the AK mode will be used by default.
106+
107+
### RAM Sub-account Role Assumption
108+
109+
You can specify obtaining credentials through RAM sub-account role assumption by using the --mode RamRoleArn. It works by exchanging temporary
110+
credentials through the AssumeRole method. An example is as follows:
111+
112+
```shell
113+
$ aliyun configure --mode RamRoleArn --profile subaccount
114+
Configuring profile 'subaccount' in 'RamRoleArn' authenticate mode...
115+
Access Key Id []: AccessKey ID
116+
Access Key Secret []: AccessKey Secret
117+
Sts Region []: cn-hangzhou
118+
Ram Role Arn []: acs:ram::******:role/ecs-test
119+
Role Session Name []: sessionname
120+
Expired Seconds []: 900
121+
Default Region Id []: cn-hangzhou
122+
Default Output Format [json]: json (Only support json)
123+
Default Language [zh|en] en:
124+
Saving profile[subaccount] ...Done.
125+
```
101126

102127
### Use an external program to get credentials
103128

@@ -111,7 +136,7 @@ Agreement：
111136

112137
Key field:
113138

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

116141
Example of the return of each credential type:
117142

@@ -136,27 +161,6 @@ Example of the return of each credential type:
136161
}
137162
```
138163

139-
- RamRoleArn
140-
141-
```json
142-
{
143-
"mode": "RamRoleArn",
144-
"access_key_id": "accessKeyId",
145-
"access_key_secret": "accessKeySecret",
146-
"ram_role_arn": "ramRoleArn",
147-
"ram_session_name": "ramSessionName"
148-
}
149-
```
150-
151-
- EcsRamRole
152-
153-
```json
154-
{
155-
"mode": "EcsRamRole",
156-
"ram_role_name": "ramRoleName"
157-
}
158-
```
159-
160164
#### Example
161165

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

225229
Otherwise, CLI treate as failure case.
226230

231+
### Use OIDC to get credentials
232+
233+
You can use the `--mode OIDC` to obtain credentials through OIDC-based SSO role assumption. An example is as follows:
234+
235+
```shell
236+
$ aliyun configure --mode OIDC --profile oidc_p
237+
Configuring profile 'oidc_p' in 'OIDC' authenticate mode...
238+
OIDC Provider ARN []: xxxx
239+
OIDC Token File []: xxx
240+
RAM Role ARN []: xxx
241+
Role Session Name []: xxx
242+
Default Region Id []: xxx
243+
Default Output Format [json]: json (Only support json)
244+
Default Language [zh|en] en:
245+
Saving profile[oidc_p] ...Done.
246+
```
247+
227248
### Enable bash/zsh auto completion
228249

229250
- Use `aliyun auto-completion` command to enable auto completion in zsh/bash

‎config/configure.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ func NewConfigureCommand() *cli.Command {
4444
Short: i18n.T(
4545
"configure credential and settings",
4646
"配置身份认证和其他信息"),
47-
Usage: "configure --mode {AK|StsToken|RamRoleArn|EcsRamRole|RsaKeyPair|RamRoleArnWithRoleName|ChainableRamRoleArn} --profile <profileName>",
47+
Usage: "configure --mode {AK|RamRoleArn|EcsRamRole|OIDC|External|CredentialsURI|ChainableRamRoleArn} --profile <profileName>",
4848
Run: func(ctx *cli.Context, args []string) error {
4949
if len(args) > 0 {
5050
return cli.NewInvalidCommandError(args[0], ctx)

‎config/profile.go

+8-5
Original file line numberDiff line numberDiff line change
@@ -32,11 +32,14 @@ import (
3232
type AuthenticateMode string
3333

3434
const (
35-
AK = AuthenticateMode("AK")
36-
StsToken = AuthenticateMode("StsToken")
37-
RamRoleArn = AuthenticateMode("RamRoleArn")
38-
EcsRamRole = AuthenticateMode("EcsRamRole")
39-
RsaKeyPair = AuthenticateMode("RsaKeyPair")
35+
AK = AuthenticateMode("AK")
36+
// Deprecated: StsToken is deprecated
37+
StsToken = AuthenticateMode("StsToken")
38+
RamRoleArn = AuthenticateMode("RamRoleArn")
39+
EcsRamRole = AuthenticateMode("EcsRamRole")
40+
// Deprecated: RsaKeyPair is deprecated
41+
RsaKeyPair = AuthenticateMode("RsaKeyPair")
42+
// Deprecated: RamRoleArnWithRoleName is deprecated, use ChainableRamRoleArn instead of
4043
RamRoleArnWithEcs = AuthenticateMode("RamRoleArnWithRoleName")
4144
ChainableRamRoleArn = AuthenticateMode("ChainableRamRoleArn")
4245
External = AuthenticateMode("External")

0 commit comments

Comments
 (0)