From aa831d2436c4bafade099d75cdb7d4cbfb8760f1 Mon Sep 17 00:00:00 2001 From: Wei-Chiu Chuang Date: Tue, 14 Jul 2026 09:28:29 -0700 Subject: [PATCH] HDDS-13454. Add user documentation for ozone s3 setsecret. Co-authored-by: Cursor --- .../01-client-interfaces/03-s3/01-s3-api.md | 16 ++++- .../03-s3/02-securing-s3.md | 63 +++++++++++++++++++ .../01-client-interfaces/04-s3a.md | 2 +- 3 files changed, 78 insertions(+), 3 deletions(-) diff --git a/docs/04-user-guide/01-client-interfaces/03-s3/01-s3-api.md b/docs/04-user-guide/01-client-interfaces/03-s3/01-s3-api.md index d442e3d870..12644117ca 100644 --- a/docs/04-user-guide/01-client-interfaces/03-s3/01-s3-api.md +++ b/docs/04-user-guide/01-client-interfaces/03-s3/01-s3-api.md @@ -107,9 +107,17 @@ awsSecret=c261b6ecabf7d37d5f9ded654b1c724adac9bd9f13e247a235e567e8296d2999 ``` :::note -Starting in Ozone 1.4.0, the secret will be **shown only once** when generated with `getsecret`. If the secret is lost, the user would have to `revokesecret` first before regenerating a new secret with `getsecret`. +Starting in Ozone 1.4.0, the secret will be **shown only once** when generated with `getsecret`. If the secret is lost, use `revokesecret` and then `getsecret` to generate a new auto-generated secret, or use `setsecret` to assign a new known value while you still have Kerberos access. ::: +To change an existing secret to a specific value, use `ozone s3 setsecret`: + +```bash +ozone s3 setsecret --secret 'my-new-secret-key' +awsAccessKey=testuser/scm@EXAMPLE.COM +awsSecret=my-new-secret-key +``` + Now, you can use the key and the secret to access the S3 endpoint: ```bash @@ -126,7 +134,7 @@ Enter 'y' to confirm S3 secret revocation for 'testuser/scm@EXAMPLE.COM': y S3 secret revoked. ``` -Ozone Manager administrators can run `ozone s3 getsecret` and `ozone s3 revokesecret` command with `-u` parameter to specify another users. +Ozone Manager administrators can run `ozone s3 getsecret`, `ozone s3 setsecret`, and `ozone s3 revokesecret` with the `-u` parameter to specify another user. ```bash # Obtained Kerberos TGT for testuser/scm@EXAMPLE.COM with kinit, @@ -135,6 +143,10 @@ ozone s3 getsecret -u om/om@EXAMPLE.COM awsAccessKey=om/om@EXAMPLE.COM awsSecret=1e9379d0424cce6669b1a501ff14834e46dee004ee868b41a313b49eabcfb68f +ozone s3 setsecret -u om/om@EXAMPLE.COM --secret 'admin-chosen-secret' +awsAccessKey=om/om@EXAMPLE.COM +awsSecret=admin-chosen-secret + ozone s3 revokesecret -u om/om@EXAMPLE.COM -y S3 secret revoked. ``` diff --git a/docs/04-user-guide/01-client-interfaces/03-s3/02-securing-s3.md b/docs/04-user-guide/01-client-interfaces/03-s3/02-securing-s3.md index af321f5255..9c0afa91f1 100644 --- a/docs/04-user-guide/01-client-interfaces/03-s3/02-securing-s3.md +++ b/docs/04-user-guide/01-client-interfaces/03-s3/02-securing-s3.md @@ -68,6 +68,69 @@ aws configure set region us-west-1 Please refer to AWS S3 documentation on how to use S3 via command line or via S3 API. +## Set Secret + +Use `ozone s3 setsecret` to change an existing S3 secret to a specific value. +Unlike `getsecret`, which auto-generates a secret when one does not exist, +`setsecret` only updates an existing secret and requires you to provide the new +secret key. + +| Command | Purpose | +| ------- | ------- | +| `ozone s3 getsecret` | Create or retrieve the initial auto-generated secret | +| `ozone s3 setsecret` | Update an existing secret to a user-chosen value | +| `ozone s3 revokesecret` | Invalidate the current secret | + +### Using the command line + +For a regular user to set their own secret: + +```bash +ozone s3 setsecret --secret '' +``` + +An Ozone administrator can set a secret for a specific user by using the `-u` flag: + +```bash +ozone s3 setsecret -u --secret '' +``` + +The command also accepts the alias `set-secret` and the short form `-s` for +`--secret`: + +```bash +ozone s3 set-secret -s '' +``` + +To print shell `export` statements for use with `eval`: + +```bash +eval $(ozone s3 setsecret -e --secret '') +``` + +Example: + +```bash +kinit -kt /etc/security/keytabs/testuser.keytab testuser/scm@EXAMPLE.COM +ozone s3 setsecret --secret 'my-new-secret-key' +awsAccessKey=testuser/scm@EXAMPLE.COM +awsSecret=my-new-secret-key +``` + +The AWS access key ID stays the same; only the secret changes. Secret keys +must be at least 8 characters long. If no secret exists yet, run +`ozone s3 getsecret` first. + +:::caution +After `setsecret`, clients still using the old secret can no longer +authenticate. Update `aws configure`, environment variables, or other client +configuration with the new secret. +::: + +For S3 multi-tenancy access IDs, use +[`ozone tenant user setsecret`](../../../administrator-guide/operations/s3-multi-tenancy/tenant-commands#set-tenant-user-secret-key) +instead. + ## Revoking Secrets via REST API To invalidate/revoke the secret, use `ozone s3 revokesecret` command. diff --git a/docs/04-user-guide/01-client-interfaces/04-s3a.md b/docs/04-user-guide/01-client-interfaces/04-s3a.md index c834979548..e921bbc976 100644 --- a/docs/04-user-guide/01-client-interfaces/04-s3a.md +++ b/docs/04-user-guide/01-client-interfaces/04-s3a.md @@ -87,7 +87,7 @@ Ozone S3 Gateway adds ETag support for S3 Multipart Upload (MPU). Object version Ozone uses the same AWS-style access key and secret key model for the S3 Gateway. - If **security is disabled**, any `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` pair can be used. -- If **security is enabled**, obtain a key and secret via `ozone s3 getsecret` (Kerberos authentication is required). See the [S3 Protocol — Security](./s3/s3-api#security) and [Securing S3](./s3/securing-s3) sections for details. +- If **security is enabled**, obtain a key and secret via `ozone s3 getsecret` (Kerberos authentication is required). To rotate an existing secret, use `ozone s3 setsecret`. See the [S3 Protocol — Security](./s3/s3-api#security) and [Securing S3](./s3/securing-s3#set-secret) sections for details. Configure S3A credentials in `core-site.xml`: