Connect to Elastic Cloud with the Elastic CLI

The Elastic CLI exposes Elastic Cloud APIs for managing organizations, Elastic Cloud Hosted deployments, and Elastic Cloud Serverless projects. These APIs manage Cloud resources and their lifecycle; they are separate from the Elasticsearch and Kibana APIs used to work with data and solution features.

This guide assumes that you have already installed the CLI. Follow these steps to configure an Elastic Cloud connection, verify authentication, and run example operations against the Elastic Cloud API.

You need:

• An installed Elastic CLI.
• Access to an Elastic Cloud organization.
• An Elastic Cloud API key with Cloud API access and roles for the resources you want to manage.

The following steps create a context named elastic-cloud that connects to the public Elastic Cloud API.

If you use Bash or zsh, keep the API key out of your shell history by capturing it in a temporary variable:

read -rs ELASTIC_CLOUD_API_KEY
		

Paste your API key at the hidden prompt, press Enter, and create the context:

elastic config context add elastic-cloud \
  --cloud-url "https://api.elastic-cloud.com" \
  --cloud-api-key "$ELASTIC_CLOUD_API_KEY"
unset ELASTIC_CLOUD_API_KEY
		

The CLI stores the API key in your operating system's credential store when one is available. Otherwise, it stores the key in the configuration file and warns you. For other ways to provide and store secrets, refer to external credentials.

Check connectivity and authentication for the new context:

elastic --use-context elastic-cloud status
		

A successful check displays a check mark next to https://api.elastic-cloud.com.

To make elastic-cloud the active context, run:

elastic config current-context set elastic-cloud
		

The remaining examples use --use-context explicitly, so changing the active context is optional.

The following commands are representative examples, not a complete list of supported operations. The resources and operations available to you depend on the permissions granted to the Elastic Cloud API key in the selected context.

List the Elastic Cloud Hosted deployments that your API key can access:

elastic --use-context elastic-cloud \
  cloud hosted deployments list-deployments
		

The response contains deployment identifiers, names, aliases, and resource details.

List the Elastic Cloud Serverless search projects that your API key can access:

elastic --use-context elastic-cloud \
  cloud serverless projects search list
		

Replace search with observability or security to list another project type:

elastic --use-context elastic-cloud \
  cloud serverless projects observability list
		

To create a Serverless project and verify access, complete the following steps:

1. List the available Serverless regions:

   elastic --use-context elastic-cloud \
     cloud serverless regions list-regions
   		

2. Create a Serverless project using one of the regions returned by the previous command. The following example creates an Observability project named cli-example in the AWS us-east-1 region, identified as aws-us-east-1 by Serverless:

   elastic --use-context elastic-cloud \
     cloud serverless projects observability create \
     --name "cli-example" \
     --region-id "aws-us-east-1" \
     --wait \
     --save-as "cli-example"
   		

   The CLI asks you to confirm the operation. The --wait option waits for the project to initialize, and --save-as stores the project's Elasticsearch and Kibana endpoints and default credentials in a context named cli-example. Refer to credential-safe project creation for more details.

   Note

   For ongoing programmatic access, we recommend using an API key with only the permissions required for your use case instead of the default credentials. The Elastic Cloud API key used in this guide can also authenticate to the new project's Elasticsearch and Kibana APIs when it has Cloud, Elasticsearch, and Kibana API access and a role that applies to all projects of the relevant type. To use it, configure the project's endpoints and the same API key in the corresponding elasticsearch and kibana blocks of a context.

3. Verify that the new context can access the project's Elasticsearch API:

   elastic --use-context cli-example es info
   		

   A successful response confirms that the project is available and the saved credentials work.

To create an Elastic Cloud Hosted deployment, complete the following steps:

1. List the deployment templates available in your chosen region:

   elastic --use-context elastic-cloud \
     cloud hosted deployment-templates get-deployment-templates-v2 \
     --region "<region-id>"
   		

   1. Refer to Elastic Cloud Hosted regions for available region identifiers on ECH.

2. Create an Elastic Cloud Hosted deployment using one of the templates returned by the previous command. The following example creates a deployment named cli-example from the General purpose template in the AWS US East (N. Virginia) region (us-east-1):

   elastic --use-context elastic-cloud \
     cloud hosted deployments create-deployment \
     --name "cli-example" \
     --region "us-east-1" \
     --template-id "aws-general-purpose"
   		

   The response contains the new deployment identifier and resource details. Refer to Manage deployments using the Elastic Cloud API for more information about regions, templates, and custom deployment configurations.

   Note

   The Elastic Cloud API key used in this guide can't authenticate to Elasticsearch or Kibana APIs on Elastic Cloud Hosted. For ongoing programmatic access to the new deployment, create an Elasticsearch API key with only the permissions required for your use case. Configure the deployment's endpoints and API key in the corresponding elasticsearch and kibana blocks of a context. You can add these blocks to elastic-cloud or create a separate context for the deployment.

• Run elastic cloud --help, elastic cloud hosted --help, or elastic cloud serverless --help to explore Cloud management commands.
• Use the Elastic CLI command reference to inspect command options and input schemas.
• Use the configuration guide to add Elasticsearch or Kibana to this context, or create a separate context for each environment.