> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kosli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# kosli snapshot ecs

> Report a snapshot of running containers in one or more AWS ECS cluster(s) to Kosli.  

## Synopsis

```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
kosli snapshot ecs ENVIRONMENT-NAME [flags]
```

Report a snapshot of running containers in one or more AWS ECS cluster(s) to Kosli.\
Skip all filtering flags to report everything running in all clusters in a given AWS account.

Use `--clusters` and/or `--clusters-regex` OR `--exclude` and/or `--exclude-regex` to filter the clusters to snapshot.
You can also filter the services within a cluster using `--services` and/or `--services-regex`. Or use `--exclude-services` and/or `--exclude-services-regex` to exclude some services.
Note that service filtering is applied to all clusters being snapshot.

All filtering options are case-sensitive.

The reported data includes cluster and service names, container image digests and creation timestamps.

To authenticate to AWS, you can either:

1. provide the AWS static credentials via flags or by exporting the equivalent KOSLI env vars (e.g. KOSLI\_AWS\_KEY\_ID)
2. export the AWS env vars (e.g. AWS\_ACCESS\_KEY\_ID).
3. Use a shared config/credentials file under the \$HOME/.aws

Option 1 takes highest precedence, while option 3 is the lowest.
More details can be found here: [https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/#specifying-credentials](https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/#specifying-credentials)

## Flags

| Flag | Type | Description |
| :- | :- | :- |
| `--aws-key-id` | string | The AWS access key ID. |
| `--aws-region` | string | The AWS region. |
| `--aws-secret-key` | string | The AWS secret access key. |
| `-C`, `--cluster` | strings | The name of the ECS cluster. (DEPRECATED: use `--clusters` instead) |
| `--clusters` | strings | \[optional] The comma-separated list of ECS cluster names to snapshot. Can't be used together with `--exclude` or `--exclude-regex`. |
| `--clusters-regex` | strings | \[optional] The comma-separated list of ECS cluster name regex patterns to snapshot. Can't be used together with `--exclude` or `--exclude-regex`. |
| `-D`, `--dry-run` | bool | \[optional] Run in dry-run mode. When enabled, no data is sent to Kosli and the CLI exits with 0 exit code regardless of any errors. |
| `--exclude` | strings | \[optional] The comma-separated list of ECS cluster names to exclude. Can't be used together with `--clusters` or `--clusters-regex`. |
| `--exclude-regex` | strings | \[optional] The comma-separated list of ECS cluster name regex patterns to exclude. Can't be used together with `--clusters` or `--clusters-regex`. |
| `--exclude-services` | strings | \[optional] The comma-separated list of ECS service names to exclude. Can't be used together with `--services` or `--services-regex`. |
| `--exclude-services-regex` | strings | \[optional] The comma-separated list of ECS service name regex patterns to exclude. Can't be used together with `--services` or `--services-regex`. |
| `-h`, `--help` | bool | help for ecs |
| `-s`, `--service-name` | string | \[deprecated] The name of the ECS service. Use `--services` instead. (DEPRECATED: it will be removed in a future release) |
| `--services` | strings | \[optional] The comma-separated list of ECS service names to snapshot. Can't be used together with `--exclude-services` or `--exclude-services-regex`. |
| `--services-regex` | strings | \[optional] The comma-separated list of ECS service name regex patterns to snapshot. Can't be used together with `--exclude-services` or `--exclude-services-regex`. |

## Flags inherited from parent commands

| Flag | Type | Description |
| :- | :- | :- |
| `-a`, `--api-token` | string | The Kosli API token. |
| `-A`, `--auto-environment` | bool | \[optional] Create the environment (with the type inferred from the snapshot subcommand) if it does not already exist, before reporting the snapshot. |
| `-c`, `--config-file` | string | \[optional] The Kosli config file path. Config is read from this path or the default only, never implicitly from the current directory. (default "\$HOME/.kosli.yml") |
| `--debug` | bool | \[optional] Print debug logs to stdout. |
| `--environment-description` | string | \[optional] The environment description. |
| `--exclude-scaling` | bool | \[optional] Exclude scaling events for snapshots. Snapshots with scaling changes will not result in new environment records. (DEPRECATED: this flag is deprecated and will be removed in a future version. Scaling events do not trigger new snapshots.) |
| `-H`, `--host` | string | \[defaulted] The Kosli endpoint. (default "[https://app.kosli.com](https://app.kosli.com)") |
| `--http-proxy` | string | \[optional] The HTTP proxy URL including protocol and port number. e.g. `http://proxy-server-ip:proxy-port` |
| `--include-scaling` | bool | \[optional] Include scaling events for snapshots. Snapshots with scaling changes will result in new environment records. (DEPRECATED: this flag is deprecated and will be removed in a future version. Scaling events do not trigger new snapshots.) |
| `-r`, `--max-api-retries` | int | \[defaulted] How many times should API calls be retried when the API host is not reachable. (default 3) |
| `--org` | string | The Kosli organization. |
| `-q`, `--quiet` | bool | \[optional] Suppress non-critical warning messages. Errors and normal output are not affected. If both `--quiet` and `--debug` are set, `--debug` wins. |

## Examples Use Cases

These examples all assume that the flags  `--api-token`, `--org`, `--host`, (and `--flow`, `--trail` when required), are [set/provided](/getting_started/install/#assigning-flags-via-environment-variables).

<AccordionGroup>
  <Accordion title="authentication to AWS using flags">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs yourEnvironmentName 
    	--aws-key-id yourAWSAccessKeyID 
    	--aws-secret-key yourAWSSecretAccessKey 
    	--aws-region yourAWSRegion 

    ```
  </Accordion>

  <Accordion title="authentication to AWS using env variables">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    export AWS_ACCESS_KEY_ID=yourAWSAccessKeyID
    export AWS_SECRET_ACCESS_KEY=yourAWSSecretAccessKey
    export AWS_REGION=yourAWSRegion

    kosli snapshot ecs yourEnvironmentName 

    ```
  </Accordion>

  <Accordion title="reporting everything running in all clusters in a given AWS account">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env 

    ```
  </Accordion>

  <Accordion title="include clusters matching a name in the AWS account">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --clusters my-cluster ...

    ```
  </Accordion>

  <Accordion title="include clusters matching a pattern in the AWS account">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --clusters-regex "^my-cluster-.*" ...

    ```
  </Accordion>

  <Accordion title="include clusters matching a list of names in the AWS account">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --clusters my-cluster1,my-cluster2 ...

    ```
  </Accordion>

  <Accordion title="exclude clusters matching a name in the AWS account">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --exclude my-cluster ...

    ```
  </Accordion>

  <Accordion title="exclude clusters matching a pattern in the AWS account">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --exclude-regex "^my-cluster-.*" ...

    ```
  </Accordion>

  <Accordion title="exclude clusters matching a list of names in the AWS account">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --exclude my-cluster1,my-cluster2 ...

    ```
  </Accordion>

  <Accordion title="include Services matching a name in one cluster">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --clusters my-cluster --services backend-app ...

    ```
  </Accordion>

  <Accordion title="include Services matching a pattern in one cluster">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --clusters my-cluster --services-regex "^backend-.*" ...

    ```
  </Accordion>

  <Accordion title="include production Services only (by naming convention) in all clusters in the AWS account">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --services-regex ".*-prod-.*" ...

    ```
  </Accordion>

  <Accordion title="include Services matching a name in all clusters in the AWS account">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --services backend-app ...

    ```
  </Accordion>

  <Accordion title="include Services matching a list of names in all clusters in the AWS account">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --services backend-app,frontend-app ...

    ```
  </Accordion>

  <Accordion title="exclude Services matching a pattern in one cluster">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --clusters my-cluster --exclude-services-regex "^backend-.*" ...

    ```
  </Accordion>

  <Accordion title="exclude Production services only (by naming convention)  in all clusters in the AWS account">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --exclude-services-regex ".*-prod-.*" ...

    ```
  </Accordion>

  <Accordion title="exclude Services matching a name in one cluster">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --clusters my-cluster --exclude-services backend-app ...

    ```
  </Accordion>

  <Accordion title="exclude Services matching a name in all clusters in the AWS account">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --exclude-services backend-app ...

    ```
  </Accordion>

  <Accordion title="exclude Services matching a list of names in all clusters in the AWS account">
    ```shell theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
    kosli snapshot ecs my-env --exclude-services backend-app,frontend-app ...
    ```
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.