|
4 | 4 |
|
5 | 5 | The goal of this project is to provide an easier way to interact with the Elastic Cloud API, ensuring each one of the provided commands is thoroughly tested. |
6 | 6 |
|
7 | | -## Installation |
8 | | - |
9 | | -The latest stable binaries can always be found on the [release page](https://github.com/elastic/ecctl/releases) or compiled from the latest on the master branch to leverage the most recently merged features. To find out more information about building from source view the steps from our [contributing page](./CONTRIBUTING.md). |
10 | | - |
11 | | -### macOS |
12 | | - |
13 | | -The simplest installation for macOS users is to install `ecctl` with `brew`. |
14 | | - |
15 | | -```console |
16 | | -$ brew tap elastic/ecctl |
17 | | -$ brew tap-pin elastic/ecctl |
18 | | -$ brew install elastic/ecctl/ecctl |
19 | | -Updating Homebrew... |
20 | | -==> Installing ecctl from elastic/ecctl |
21 | | -... |
22 | | -==> Summary |
23 | | -🍺 /usr/local/Cellar/ecctl/1.0.0: 6 files, 13MB, built in 7 seconds |
24 | | -``` |
25 | | - |
26 | | -#### Note: to get the autocompletions working they must be sourced from your shell profile |
27 | | - |
28 | | -## Linux based OS |
29 | | - |
30 | | -<!-- TODO: Update this with the approparate repo when applicable --> |
31 | | - |
32 | | -## Configuration Settings and Precedence |
33 | | - |
34 | | -In order for `ecctl` to be able to communicate with the API, it needs to have a set of configuration parameters defined. |
35 | | -These parameters can be set in a configuration file, through environment variables, or at runtime using the CLI's global flags. |
36 | | - |
37 | | -The hierarchy is as follows listed from higher precedence to lower: |
38 | | - |
39 | | -1. Command line flags `--region`, `--host`, `--user`, `--pass`. |
40 | | -2. Environment variables. |
41 | | -3. Shared configuration file `$HOME/.ecctl/config.<json|toml|yaml|hcl>`. |
42 | | - |
43 | | -## Generating a configuration file |
44 | | - |
45 | | -If it's your first time using `ecctl`, you might want to use the `init` command to assist you |
46 | | -in generating a configuration file. The resulting configuration file will be saved under `~/.ecctl/config.json`: |
47 | | - |
48 | | -```console |
49 | | -$ ecctl init |
50 | | -Welcome to the Elastic Cloud CLI! This command will guide you through authenticating and setting some default values. |
51 | | - |
52 | | -Missing configuration file, woud you like to initialise it? [y/n]: y |
53 | | -Enter the URL of the Elastic Cloud API or your ECE installation: https://api.elastic-cloud.com |
54 | | - |
55 | | -What default output format would you like? |
56 | | - [1] text - Human-readable output format, commands with no output templates defined will fall back to JSON. |
57 | | - [2] json - JSON formatted output API responses. |
58 | | - |
59 | | -Please enter a choice: 1 |
60 | | - |
61 | | - |
62 | | -Which authentication mechanism would you like to use? |
63 | | - [1] API Keys (Recommended). |
64 | | - [2] Username and Password login. |
65 | | - |
66 | | -Please enter your choice: 1 |
67 | | - |
68 | | -Paste your API Key and press enter: xxxxx |
69 | | - |
70 | | -Your credentials seem to be valid, and show you're authenticated as "user". |
71 | | - |
72 | | -You're all set! Here are some commands to try: |
73 | | - $ ecctl auth user key list |
74 | | - $ ecctl deployment elasticsearch list |
75 | | -``` |
76 | | - |
77 | | -## Elastic Cloud authentication |
78 | | - |
79 | | -Elastic Cloud uses API keys to authenticate users against its API. Additionally, it supports |
80 | | -the usage of [JWT](https://jwt.io/) to validate authenticated clients. The preferred authentication method is API keys. |
81 | | - |
82 | | -There's two ways to authenticate against the Elastic Cloud API using `ecctl`: |
83 | | - |
84 | | -* **Specifying an API key using the `--apikey` flag**. |
85 | | -* Specifying a `--user` and `--pass` flags. |
86 | | - |
87 | | -The first method requires the user to already have an API key, if this is the case, all the outgoing API requests will use an Authentication API key header. |
88 | | - |
89 | | -The second method uses the `user` and `pass` values to obtain a valid JWT token, that token is then used as the Authentication Bearer header for every API call. A goroutine that refreshes the token every minute is started, so that the token doesn't expire while we're performing actions. |
90 | | - |
91 | | -### Shared configuration file |
92 | | - |
93 | | -Below is an example `YAML` configuration file `$HOME/.ecctl/config.yaml` that will effectively point and configure the binary for Elastic Cloud: |
94 | | - |
95 | | -```yaml |
96 | | -host: https://api.elastic-cloud.com # URL of Elastic Cloud or your ECE installation. |
97 | | -region: us-east-1 # For ECE installations you can just omit this setting. |
98 | | - |
99 | | -# Credentials |
100 | | -## apikey is the preferred authentication mechanism. |
101 | | -apikey: bWFyYzo4ZTJmNmZkNjY5ZmQ0MDBkOTQ3ZjI3MTg3ZWI5MWZhYjpOQktHY05jclE0cTBzcUlnTXg3QTd3 |
102 | | - |
103 | | -## username and password can be used, specially when no API key is available. |
104 | | -user: username |
105 | | -pass: password |
106 | | -``` |
107 | | -
|
108 | | -### Environment variables |
109 | | -
|
110 | | -The same settings can be defined as environment variables instead of a configuration file or to override certain settings of the `YAML` file. If setting environment variables, you'll need to prefix the configuration parameter with `EC_` and capitalize the setting, i.e. `EC_HOST` or `EC_USER`. |
111 | | - |
112 | | -```sh |
113 | | -export EC_APIKEY=bWFyYzo4ZTJmNmZkNjY5ZmQ0MDBkOTQ3ZjI3MTg3ZWI5MWZhYjpOQktHY05jclE0cTBzcUlnTXg3QTd3 |
114 | | -``` |
115 | | - |
116 | | -#### Special Environment Variables |
117 | | - |
118 | | -```sh |
119 | | -export EC_CONFIG=$HOME/.ecctl/cloud.yaml |
120 | | -``` |
121 | | - |
122 | | -`EC_REGIONS` will define autocomplete entries for the `--region` flag, though there is no validation and it is not environment aware (e.g. no different list is provided for staging vs production). |
123 | | - |
124 | | -```sh |
125 | | -export EC_REGIONS=="ap-northeast-1 ap-southeast-1 ap-southeast-2 aws-eu-central-1 eu-west-1 gcp-europe-west1 gcp-europe-west3 gcp-us-central1 gcp-us-west1 sa-east-1 us-east-1 us-west-1 us-west-2" |
126 | | -``` |
127 | | - |
128 | | -## Multiple configuration support |
129 | | - |
130 | | -`ecctl` supports having multiple configuration files out of the box. This allows for easy management of multiple environments or specialized targets. By default it will use `$HOME/.ecctl/config.<json|toml|yaml|hcl>`, but when the `--config` flag is specified, it will append the `--config` name to the file: |
131 | | - |
132 | | -```console |
133 | | -# Default behaviour |
134 | | -$ ecctl version |
135 | | -# will use ~/.ecctl/staging.yaml |
136 | | -
|
137 | | -# When an environment is specified, the configuration file used will change |
138 | | -$ ecctl version --config ece |
139 | | -# will use ~/.ecctl/ece.yaml |
140 | | -``` |
141 | | - |
142 | | -## Output format |
143 | | - |
144 | | -The `--output` flag allows for the response to be presented in a particular way (see `ecctl help` for an updated list of allowed formats). The default formatter behavior is to fallback to `json` when there's no _text_ format template or if the formatting fails. |
145 | | - |
146 | | -## Custom formatting |
147 | | - |
148 | | -`ecctl` supports a global `--format` flag which can be passed to any existing command or subcommand. |
149 | | -Using the `--format` flag allows you to obtain a specific part of a command response that might not have been shown before with the default `--output=text`. The `--format` internally uses Go templates which means that you can use the power of the Go built-in [`text/templates`](https://golang.org/pkg/text/template/) on demmand. |
150 | | - |
151 | | -### Examples |
152 | | - |
153 | | -Obtaining the ID, Version and health status |
154 | | - |
155 | | -```console |
156 | | -$ ecctl elasticsearch list --format '{{.ClusterID}} {{.PlanInfo.Current.Plan.Elasticsearch.Version}} {{.Healthy}}' |
157 | | -a2c4f423c1014941b75a48292264dd25 6.7.0 true |
158 | | -a4f29ff3ba554e69a1e1b40c3ee1b6e3 6.7.0 true |
159 | | -5e29960763ef496ea8cf6a5371328a6a 6.7.0 true |
160 | | -53023f28d68b4b329d9d913f110709d2 6.7.0 true |
161 | | -``` |
162 | | - |
163 | | -Since the template is executed we can also embed logic inside of the template to filter the results. |
164 | | - |
165 | | -```console |
166 | | -$ export EC_FORMAT='{{range .Elasticsearch.DefaultPlugins}}{{if eq . "discovery-file" }}{{$.Version}}{{end}}{{end}}' |
167 | | -# Since the template is executed on every item of the list, filter the empty lines to have a cleaner output. |
168 | | -$ ecctl stack list --format "${EC_FORMAT}" | sed '/^\s*$/d' |
169 | | -
|
170 | | -
|
171 | | -6.2.3 |
172 | | -$ unset EC_FORMAT |
173 | | -``` |
| 7 | +To get started with Elastic Cloud Control, see the [official documentation](https://www.elastic.co/guide/en/ecctl/current/index.html). |
174 | 8 |
|
175 | 9 | ## Contributing |
176 | 10 |
|
177 | | -See the contribution guidelines specified in the [CONTRIBUTING](./CONTRIBUTING.md) doc. |
178 | | - |
179 | | -## Release Process |
180 | | - |
181 | | -See the [release guide](./developer_docs/RELEASE.md). |
182 | | - |
183 | | -## Full command help |
184 | | - |
185 | | -* [ecctl command help](./docs/ecctl.md) |
| 11 | +If you are interested in becoming a part of this project, take a look at our [contribution guidelines](./CONTRIBUTING.md). |
0 commit comments