Skip to content

Commit ededc9a

Browse files
kilfoylekilfoyle
authored
Docs: add usages examples to ecctl docs (#284)
This adds usage examples into the Cloud ecctl guide, basically matching the CRUD examples we have for the public API.
1 parent ef15eff commit ededc9a

File tree

1 file changed

+265
-20
lines changed

1 file changed

+265
-20
lines changed

‎docs/ecctl-getting-started.asciidoc

Lines changed: 265 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
beta[]
55

6-
{p} is the CLI for the Elasticsearch Service and Elastic Cloud Enterprise APIs.
6+
{p} is the CLI for the Elastic Cloud Enterprise API.
77
It wraps typical operations commonly needed by operators within a single command line tool.
88

99
Benefits of {p}:
@@ -252,47 +252,292 @@ https://golang.org/pkg/text/template/[`text/templates`] on demand.
252252
[id="{p}-examples"]
253253
== Usage examples
254254

255-
To create your first deployment, use the `ecctl deployment create` command, which accepts https://github.com/elastic/ecctl/blob/master/docs/ecctl_deployment_create.md#examples[a deployment description in the form of a JSON file] and a stack version and name as inputs.
255+
Once you've <<{p}-installing,installed>> and <<{p}-configuring,configured>> {p} you're ready to take it for a test drive. Try these examples with basic Create, Read, Update and Delete operations using {p}:
256256

257-
[source,sh]
257+
* <<{p}-example-list-deployments,List deploymments>>
258+
* <<{p}-example-create-deployment,Create a deployment>>
259+
* <<{p}-example-update-deployment,Update a deployment>>
260+
* <<{p}-example-delete-deployment,Delete a deployment>>
261+
262+
263+
To compare the {p} commands against their API equivalents, see the {cloud}/ec-api-examples.html[API examples].
264+
265+
266+
267+
[id="{p}-example-list-deployments"]
268+
=== List deployments
269+
270+
As a first example of using {p}, run the <<ecctl_deployment_list,{p} deployment list>> command to retrieve information about existing deployments. This is a good way to check if {p} is configured correctly and if you have any deployments already created.
271+
272+
[source, sh]
273+
--
274+
ecctl deployment list
275+
--
276+
277+
[source, sh]
278+
--
279+
ID NAME ELASTICSEARCH KIBANA APM APPSEARCH
280+
00be03849b6a49c1a6541e3ccb5958d2 marvin 00be03849b6a49c1a6541e3ccb5958d2 266e456acf257588a9cde6fb4569d4a0 78c096c22e12408b878083b2d5ff6bcf -
281+
147cdeace6404c3e4b5018e1401647e4 biggerdata 147cdeace6404c3e4b5018e1401647e4 443a9df7b33952f45921c5823cbad4bc 4678ce52d45547e463455ede663cb4a4 -
282+
--
283+
284+
[id="{p}-example-create-deployment"]
285+
=== Create a deployment
286+
287+
Let's create a basic deployment. Elasticsearch Service supports {cloud}/ec-getting-started-templates.html[deployment templates], which pre-configure the Elastic Stack components in your deployment to best suit your particular use case. For this example, use Google Cloud Platform (GCP) to host the deployment in region `US Central 1 (Iowa)`. To know which deployment options are available by platform, see {cloud}/ec-regions-templates-instances.html[available regions, deployment templates and instance configurations].
288+
289+
Copy the following JSON payload and save it as file `create-deployment.json`.
290+
291+
[source, json]
292+
--
293+
{
294+
"name": "My first ecctl deployment",
295+
"resources": {
296+
"elasticsearch": [
297+
{
298+
"region": "gcp-us-central1", <1>
299+
"ref_id": "main-elasticsearch",
300+
"plan": {
301+
"cluster_topology": [
302+
{
303+
"node_type": {
304+
"master": true,
305+
"data": true,
306+
"ingest": true,
307+
"ml": false
308+
},
309+
"instance_configuration_id": "gcp.data.highio.1", <2>
310+
"zone_count": 2, <3>
311+
"size": {
312+
"resource": "memory",
313+
"value": 2048 <4>
314+
}
315+
}
316+
],
317+
"elasticsearch": {
318+
"version": "7.6.0" <5>
319+
},
320+
"deployment_template": {
321+
"id": "gcp-io-optimized" <6>
322+
}
323+
}
324+
}
325+
],
326+
"kibana": [
327+
{
328+
"region": "gcp-us-central1",
329+
"elasticsearch_cluster_ref_id": "main-elasticsearch",
330+
"ref_id": "main-kibana",
331+
"plan": {
332+
"cluster_topology": [
333+
{
334+
"instance_configuration_id": "gcp.kibana.1",
335+
"zone_count": 1, <7>
336+
"size": {
337+
"resource": "memory",
338+
"value": 1024 <8>
339+
}
340+
}
341+
],
342+
"kibana": {
343+
"version": "7.6.0" <9>
344+
}
345+
}
346+
}
347+
],
348+
"apm": [
349+
{
350+
"region": "gcp-us-central1",
351+
"elasticsearch_cluster_ref_id": "main-elasticsearch",
352+
"ref_id": "main-apm",
353+
"plan": {
354+
"cluster_topology": [
355+
{
356+
"instance_configuration_id": "gcp.apm.1",
357+
"zone_count": 1, <10>
358+
"size": {
359+
"resource": "memory",
360+
"value": 512 <11>
361+
}
362+
}
363+
],
364+
"apm": {
365+
"version": "7.6.0" <12>
366+
}
367+
}
368+
}
369+
]
370+
}
371+
}
372+
--
373+
<1> The region for the Elasticsearch cluster
374+
<2> Instance configuration ID
375+
<3> The number of availability zones for the Elasticsearch cluster
376+
<4> The amount of memory allocated for each Elasticsearch node
377+
<5> The version of the Elasticsearch cluster
378+
<6> The template on which to base the deployment
379+
<7> The number of availability zones for Kibana
380+
<8> The amount of memory allocated for Kibana
381+
<9> The version of the Kibana instance
382+
<10> The number of availability zones for APM
383+
<11> The amount of memory allocated for APM
384+
<12> The version of the APM instance
385+
386+
This JSON contains the settings for a highly available Elasticsearch cluster deployed across two availability zones, a single instance of Kibana, and a single APM server.
387+
388+
Run the <<ecctl_deployment_create,{p} deployment create>> command with `create-deployment.json` as a parameter. For this and other commands, you can add an optional `--track` parameter to monitor the progress.
389+
390+
[source, sh]
391+
--
392+
ecctl deployment create -f create-deployment.json
393+
--
394+
395+
[source, sh]
258396
--
259-
ecctl deployment create --file ./deployment.json --name=my-new-deployment --version=7.4.1
260397
{
261398
"created": true,
262-
"id": "c44ad3fa558a237d0c17d0f4273801df",
263-
"name": "my example cluster",
399+
"id": "7229888e7bf8350c7e4d07d7374171c0",
400+
"name": "My first ecctl deployment",
264401
"resources": [
265402
{
266-
"cloud_id": "my_elasticsearch_cluster:REDACTED",
403+
"cloud_id": "My_first_ecctl_deployment:dXMtY2VudHJhbDEuZ2NwLmZvdW5kaXQubm8kYjFlZWVjOGQ0YWVlNGY3ZDgxNTM2Zjc1ZjZhN2Y1MDgkM2ViZTAzNmI0NDhkNDc3Y2E2ZTJjZTQ5NmE4ZDQ5ODA=",
267404
"credentials": {
268405
"password": "REDACTED",
269406
"username": "elastic"
270407
},
271-
"id": "edd8b0bf7ece46dab47acc7074a7f191",
408+
"id": "b1eeec8d4aee4f7d81536f75f6a7f508",
409+
"kind": "elasticsearch",
410+
"ref_id": "main-elasticsearch",
411+
"region": "gcp-us-central1"
412+
},
413+
{
414+
"elasticsearch_cluster_ref_id": "main-elasticsearch",
415+
"id": "3ebe036b448d477ca6e2ce496a8d4980",
416+
"kind": "kibana",
417+
"ref_id": "main-kibana",
418+
"region": "gcp-us-central1"
419+
},
420+
{
421+
"elasticsearch_cluster_ref_id": "main-elasticsearch",
422+
"id": "5a03472f6dfe4f17acbe62622823b9cb",
423+
"kind": "apm",
424+
"ref_id": "main-apm",
425+
"region": "gcp-us-central1",
426+
"secret_token": "zfufcfe15eCVJk78b5"
427+
}
428+
]
429+
}
430+
--
431+
432+
The response indicates that the request was submitted successfully. It includes the `elastic` user password, which you can use to log in to Kibana or to access the Elasticsearch REST API. Make a note of the deployment ID, which you will use in the next example.
433+
434+
[id="{p}-example-update-deployment"]
435+
=== Update a deployment
436+
437+
Now that you have used {p} to create a deployment, you can scale it up, by increasing the size of the Elasticsearch data nodes from 1024 to 4096 MB.
438+
439+
Copy the following JSON payload and save it as file `update-deployment.json`.
440+
441+
[source, json]
442+
--
443+
{
444+
"prune_orphans": false,
445+
"resources": {
446+
"elasticsearch": [
447+
{
448+
"region": "gcp-us-central1",
449+
"ref_id": "main-elasticsearch",
450+
"plan": {
451+
"cluster_topology": [
452+
{
453+
"node_type": {
454+
"master": true,
455+
"data": true,
456+
"ingest": true,
457+
"ml": false
458+
},
459+
"instance_configuration_id": "gcp.data.highio.1",
460+
"zone_count": 2,
461+
"size": {
462+
"resource": "memory",
463+
"value": 4096
464+
}
465+
}
466+
],
467+
"elasticsearch": {
468+
"version": "7.6.0"
469+
},
470+
"deployment_template": {
471+
"id": "gcp-io-optimized"
472+
}
473+
}
474+
}
475+
]
476+
}
477+
}
478+
--
479+
480+
The JSON body is similar to what we used to create the deployment, with the following differences:
481+
482+
- The name of the deployment can be modified or it will stay the same if not specified.
483+
- A `prune_orphans` parameter is added. This important parameter specifies how resources not included in the JSON should be handled:
484+
* if `true`, those resources not included are removed
485+
* if `false`, those resources not included are kept intact
486+
487+
In this example, prune_orphans is set to `false`, so the Kibana and APM instances are not changed or removed, while the Elasticsearch resource is modified according to the configuration specified in the JSON file.
488+
489+
[source, json]
490+
--
491+
ecctl deployment update $DEPLOYMENT_ID -f update-deployment.json
492+
--
493+
* `$DEPLOYMENT_ID` is the ID for the deployment that was created in the previous <<{p}-example-create-deployment,create a deployment>> example.
494+
495+
[source, json]
496+
--
497+
{
498+
"id": "20e174f6800c55261e4dfcc278b6a004",
499+
"name": "My second ecctl deployment",
500+
"resources": [
501+
{
502+
"cloud_id": "My_second_ecctl_deployment:dXMtY2VudHJhbDEuZ2NwLmZvdW5kaXQubm8kYjc0OWU2ZWExN2Y4NDg5Yzg4Y2UyOTVjZTA4ZDVjNWUkNTliZWJiYjE3ZmFkNDk2MWEwMmNkMDRmNzYyOWYxMTk=",
503+
"id": "b749e6ea17f8489c88ce295ce08d5c5e",
272504
"kind": "elasticsearch",
273-
"ref_id": "my-es-cluster",
274-
"region": "ece-region"
505+
"ref_id": "main-elasticsearch",
506+
"region": "gcp-us-central1"
275507
},
276508
{
277-
"elasticsearch_cluster_ref_id": "my-es-cluster",
278-
"id": "44dd3575894b4fc89bd600f56d1c130d",
509+
"elasticsearch_cluster_ref_id": "main-elasticsearch",
510+
"id": "59bebbb17fad4961a02cd04f7629f119",
279511
"kind": "kibana",
280-
"ref_id": "my-kibana-instance",
281-
"region": "ece-region"
512+
"ref_id": "main-kibana",
513+
"region": "gcp-us-central1"
282514
},
283515
{
284-
"elasticsearch_cluster_ref_id": "my-es-cluster",
285-
"id": "9868cd370bdc469a8364ece4fe0db16d",
516+
"elasticsearch_cluster_ref_id": "main-elasticsearch",
517+
"id": "1ec19461253c4175a2cea6b3ccc399a8",
286518
"kind": "apm",
287-
"ref_id": "my-apm-instance",
288-
"region": "ece-region",
289-
"secret_token": "REDACTED"
519+
"ref_id": "main-apm",
520+
"region": "gcp-us-central1"
290521
}
291522
]
292523
}
293524
--
294525

295-
There’s much more you can use ecctl for. You can explore ecctl and its various commands by issuing `ecctl <command> <help>` to see the different options that we support.
526+
[id="{p}-example-delete-deployment"]
527+
=== Delete a deployment
528+
529+
In this last example, you can use the <<ecctl_deployment_shutdown,{p} deployment shutdown>> command to delete the deployment that you created.
530+
531+
[source, json]
532+
--
533+
ecctl deployment shutdown $DEPLOYMENT_ID
534+
--
535+
* `$DEPLOYMENT_ID` is the ID for the deployment that was created in the previous <<{p}-example-create-deployment,create a deployment>> example.
536+
537+
On running this and other destructive commands, {p} prompts you with a confirmation message. Use the `--force` option to skip the confirmation step, if you are using {p} for automation.
538+
539+
To see the different options that {p} supports, run `ecctl <command> <help>`.
540+
296541

297542
// NR as per Omer, ecctl elasticsearch is no longer supported (do we need to mention this in the release notes for beta1?)
298543
////

0 commit comments

Comments
 (0)