Skip to content

Commit 8a2d6f6

Browse files
marclopmarclop
authored
docs: Improve elasticsearch keystore cmd help (#508)
Improves the documentation for the `deployment elasticsearch keystore` command adding more information about how to format the file that is passed to the command, where to find more info and a couple of examples. Signed-off-by: Marc Lopez Rubio <marc5.12@outlook.com>
1 parent cf59a55 commit 8a2d6f6

File tree

3 files changed

+155
-15
lines changed

3 files changed

+155
-15
lines changed

‎cmd/deployment/elasticsearch/keystore/update.go

Lines changed: 50 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -31,10 +31,54 @@ import (
3131
"github.com/elastic/ecctl/pkg/ecctl"
3232
)
3333

34-
const updateLong = `Changes the contents of the Elasticsearch resource keystore from the
35-
specified deployment by using the PATCH method. The payload is a partial payload where
36-
any ignored current keystore items are not removed, unless the secrets are
37-
set to "null": {"secrets": {"my-secret": null}}.`
34+
const updateLong = `Changes the contents of the Elasticsearch resource keystore from the specified
35+
deployment by using the PATCH method. The payload is a partial payload where any
36+
omitted current keystore items are not removed, unless the secrets are set to "null":
37+
{"secrets": {"my-secret": null}}.
38+
39+
The contents of the specified file should be formatted to match the Elasticsearch Service
40+
API "KeystoreContents" model. For more information on format, see the ESS API reference:
41+
https://www.elastic.co/guide/en/cloud/current/definitions.html#KeystoreContents.
42+
`
43+
44+
const updateExample = `# Set credentials for a GCS snapshot repository
45+
$ cat gcs-creds.json
46+
{
47+
"secrets": {
48+
"gcs.client.default.credentials_file": {
49+
"as_file": true,
50+
"value": {
51+
"type": "service_account",
52+
"project_id": "project-id",
53+
"private_key_id": "key-id",
54+
"private_key": "-----BEGIN PRIVATE KEY-----\nprivate-key\n-----END PRIVATE KEY-----\n",
55+
"client_email": "service-account-email",
56+
"client_id": "client-id",
57+
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
58+
"token_uri": "https://accounts.google.com/o/oauth2/token",
59+
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
60+
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/service-account-email"
61+
}
62+
}
63+
}
64+
}
65+
$ ecctl deployment elasticsearch keystore set --file=gcs-creds.json <Deployment ID>
66+
...
67+
# Set multiple secrets in one playload
68+
$ cat multiple.json
69+
{
70+
"secrets": {
71+
"my-secret": {
72+
"value": "my-value"
73+
},
74+
"my-other-secret": {
75+
"value": "my-other-value"
76+
}
77+
}
78+
}
79+
$ ecctl deployment elasticsearch keystore set --file=multiple.json <Deployment ID>
80+
...
81+
`
3882

3983
var (
4084
errReadingDefPrefix = "failed reading keystore secret definition"
@@ -44,6 +88,7 @@ var (
4488
var updateCmd = &cobra.Command{
4589
Use: "update <deployment id> [--ref-id <ref-id>] {--file=<filename>.json}",
4690
Long: updateLong,
91+
Example: updateExample,
4792
Aliases: []string{"set"},
4893
Short: "Updates the contents of an Elasticsearch keystore",
4994
PreRunE: sdkcmdutil.MinimumNArgsAndUUID(1),
@@ -74,6 +119,6 @@ var updateCmd = &cobra.Command{
74119
func init() {
75120
Command.AddCommand(updateCmd)
76121
updateCmd.Flags().String("ref-id", "", "Optional ref_id to use for the Elasticsearch resource, auto-discovered if not specified.")
77-
updateCmd.Flags().StringP("file", "p", "", "Required json formatted file path with the keystore secret contents.")
122+
updateCmd.Flags().StringP("file", "f", "", "Required json formatted file path with the keystore secret contents.")
78123
updateCmd.MarkFlagFilename("file", "json")
79124
}

‎docs/ecctl_deployment_elasticsearch_keystore_update.adoc

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,20 +6,67 @@ Updates the contents of an Elasticsearch keystore
66
[float]
77
=== Synopsis
88

9-
Changes the contents of the Elasticsearch resource keystore from the
10-
specified deployment by using the PATCH method. The payload is a partial payload where
11-
any ignored current keystore items are not removed, unless the secrets are
12-
set to "null": {"secrets": {"my-secret": null}}.
9+
Changes the contents of the Elasticsearch resource keystore from the specified
10+
deployment by using the PATCH method. The payload is a partial payload where any
11+
omitted current keystore items are not removed, unless the secrets are set to "null":
12+
{"secrets": {"my-secret": null}}.
13+
14+
The contents of the specified file should be formatted to match the Elasticsearch Service
15+
API "KeystoreContents" model. For more information on format, see the ESS API reference:
16+
https://www.elastic.co/guide/en/cloud/current/definitions.html#KeystoreContents.
1317

1418
----
1519
ecctl deployment elasticsearch keystore update <deployment id> [--ref-id <ref-id>] {--file=<filename>.json} [flags]
1620
----
1721

22+
[float]
23+
=== Examples
24+
25+
----
26+
# Set credentials for a GCS snapshot repository
27+
$ cat gcs-creds.json
28+
{
29+
"secrets": {
30+
"gcs.client.default.credentials_file": {
31+
"as_file": true,
32+
"value": {
33+
"type": "service_account",
34+
"project_id": "project-id",
35+
"private_key_id": "key-id",
36+
"private_key": "-----BEGIN PRIVATE KEY-----\nprivate-key\n-----END PRIVATE KEY-----\n",
37+
"client_email": "service-account-email",
38+
"client_id": "client-id",
39+
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
40+
"token_uri": "https://accounts.google.com/o/oauth2/token",
41+
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
42+
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/service-account-email"
43+
}
44+
}
45+
}
46+
}
47+
$ ecctl deployment elasticsearch keystore set --file=gcs-creds.json <Deployment ID>
48+
...
49+
# Set multiple secrets in one playload
50+
$ cat multiple.json
51+
{
52+
"secrets": {
53+
"my-secret": {
54+
"value": "my-value"
55+
},
56+
"my-other-secret": {
57+
"value": "my-other-value"
58+
}
59+
}
60+
}
61+
$ ecctl deployment elasticsearch keystore set --file=multiple.json <Deployment ID>
62+
...
63+
----
64+
1865
[float]
1966
=== Options
2067

2168
----
22-
-p, --file string Required json formatted file path with the keystore secret contents.
69+
-f, --file string Required json formatted file path with the keystore secret contents.
2370
-h, --help help for update
2471
--ref-id string Optional ref_id to use for the Elasticsearch resource, auto-discovered if not specified.
2572
----

‎docs/ecctl_deployment_elasticsearch_keystore_update.md

Lines changed: 53 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,67 @@ Updates the contents of an Elasticsearch keystore
44

55
### Synopsis
66

7-
Changes the contents of the Elasticsearch resource keystore from the
8-
specified deployment by using the PATCH method. The payload is a partial payload where
9-
any ignored current keystore items are not removed, unless the secrets are
10-
set to "null": {"secrets": {"my-secret": null}}.
7+
Changes the contents of the Elasticsearch resource keystore from the specified
8+
deployment by using the PATCH method. The payload is a partial payload where any
9+
omitted current keystore items are not removed, unless the secrets are set to "null":
10+
{"secrets": {"my-secret": null}}.
11+
12+
The contents of the specified file should be formatted to match the Elasticsearch Service
13+
API "KeystoreContents" model. For more information on format, see the ESS API reference:
14+
https://www.elastic.co/guide/en/cloud/current/definitions.html#KeystoreContents.
15+
1116

1217
```
1318
ecctl deployment elasticsearch keystore update <deployment id> [--ref-id <ref-id>] {--file=<filename>.json} [flags]
1419
```
1520

21+
### Examples
22+
23+
```
24+
# Set credentials for a GCS snapshot repository
25+
$ cat gcs-creds.json
26+
{
27+
"secrets": {
28+
"gcs.client.default.credentials_file": {
29+
"as_file": true,
30+
"value": {
31+
"type": "service_account",
32+
"project_id": "project-id",
33+
"private_key_id": "key-id",
34+
"private_key": "-----BEGIN PRIVATE KEY-----\nprivate-key\n-----END PRIVATE KEY-----\n",
35+
"client_email": "service-account-email",
36+
"client_id": "client-id",
37+
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
38+
"token_uri": "https://accounts.google.com/o/oauth2/token",
39+
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
40+
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/service-account-email"
41+
}
42+
}
43+
}
44+
}
45+
$ ecctl deployment elasticsearch keystore set --file=gcs-creds.json <Deployment ID>
46+
...
47+
# Set multiple secrets in one playload
48+
$ cat multiple.json
49+
{
50+
"secrets": {
51+
"my-secret": {
52+
"value": "my-value"
53+
},
54+
"my-other-secret": {
55+
"value": "my-other-value"
56+
}
57+
}
58+
}
59+
$ ecctl deployment elasticsearch keystore set --file=multiple.json <Deployment ID>
60+
...
61+
62+
```
63+
1664
### Options
1765

1866
```
19-
-p, --file string Required json formatted file path with the keystore secret contents.
67+
-f, --file string Required json formatted file path with the keystore secret contents.
2068
-h, --help help for update
2169
--ref-id string Optional ref_id to use for the Elasticsearch resource, auto-discovered if not specified.
2270
```

0 commit comments

Comments
 (0)