# Manage Amazon Managed Service for Prometheus workspaces A *workspace* is a logical space dedicated to the storage and querying of Prometheus metrics. A workspace supports fine-grained access control for authorizing its management such as update, list, describe, and delete, and the ingestion and querying of metrics. You can have one or more workspaces in each Region in your account. Use the procedures in this section to create and manage your Amazon Managed Service for Prometheus workspaces. **Topics** + [Create a Amazon Managed Service for Prometheus workspace](AMP-create-workspace.md) + [Configure your workspace](AMP-workspace-configuration.md) + [Edit a workspace alias](AMP-edit-workspace.md) + [Find your Amazon Managed Service for Prometheus workspace details, including ARN](AMP-find-workspace-details.md) + [Delete an Amazon Managed Service for Prometheus workspace](AMP-delete-workspace.md) # Create a Amazon Managed Service for Prometheus workspace Follow these steps to create a Amazon Managed Service for Prometheus workspace. You can choose to use the AWS CLI or the Amazon Managed Service for Prometheus console. **Note** If you are running an Amazon EKS cluster, you can also create a new workspace using [AWS Controllers for Kubernetes](integrating-ack.md). **To create a workspace using the AWS CLI** 1. Enter the following command to create the workspace. This example creates a workspace named `my-first-workspace`, but you can use a different alias (or none) if you want. Workspace aliases are friendly names that help you identify your workspaces. They do not have to be unique. Two workspaces can have the same alias, but all workspaces have unique workspace IDs, which are generated by Amazon Managed Service for Prometheus. (Optional) To use your own KMS key to encrypt data stored in your workspace, you can include the `kmsKeyArn` parameter with the AWS KMS key to use. While Amazon Managed Service for Prometheus does not charge you for using customer managed keys, there may be costs associated with keys from AWS Key Management Service. For more information about Amazon Managed Service for Prometheus encryption of data in the workspace, or how to create, manage, and use your own customer managed key, see [Encryption at rest](encryption-at-rest-Amazon-Service-Prometheus.md). Parameters in brackets (`[]`) are optional, do not include the brackets in your command. ``` aws amp create-workspace [--alias my-first-workspace] [--kmsKeyArn arn:aws:aps:us-west-2:111122223333:workspace/ws-sample-1234-abcd-56ef-7890abcd12ef] [--tags Status=Secret,Team=My-Team] ``` This command returns the following data: + `workspaceId` is the unique ID for this workspace. Make a note of this ID. + `arn` is the ARN for this workspace. + `status` is the current status of the workspace. Immediately after you create the workspace, this will probably be `CREATING`. + `kmsKeyArn` is the customer managed key used to encrypt the workspace data, if given. **Note** Workspaces created with customer managed keys cannot use [AWS managed collectors](AMP-collector.md) for ingestion. Choose whether to use customer managed keys or AWS owned keys carefully. Workspaces created with customer managed keys can't be converted to use AWS owned keys later (and vice versa). + `tags` lists the workspace's tags, if any. 1. If your `create-workspace` command returns a status of `CREATING`, you can then enter the following command to determine when the workspace is ready. Replace *my-workspace-id* with the value that the `create-workspace` command returned for `workspaceId`. ``` aws amp describe-workspace --workspace-id my-workspace-id ``` When the `describe-workspace` command returns `ACTIVE` for `status`, the workspace is ready to use. **To create a workspace using the Amazon Managed Service for Prometheus console** 1. Open the Amazon Managed Service for Prometheus console at [https://console.aws.amazon.com/prometheus/](https://console.aws.amazon.com/prometheus/home). 1. Choose **Create**. 1. For **Workspace alias**, enter an alias for the new workspace. Workspace aliases are friendly names that help you identify your workspaces. They do not have to be unique. Two workspaces can have the same alias, but all workspaces have unique workspace IDs, which are generated by Amazon Managed Service for Prometheus. 1. (Optional) To use your own KMS key to encrypt data stored in your workspace, you can select **Customize encryption settings**, and choose the AWS KMS key to use (or create a new one). You can choose a key in your account from the drop down list, or enter the ARN for any key that you have access to. While Amazon Managed Service for Prometheus does not charge you for using customer managed keys, there may be costs associated with keys from AWS Key Management Service. For more information about Amazon Managed Service for Prometheus encryption of data in the workspace, or how to create, manage, and use your own, customer managed key, see [Encryption at rest](encryption-at-rest-Amazon-Service-Prometheus.md). **Note** Workspaces created with customer managed keys cannot use [AWS managed collectors](AMP-collector.md) for ingestion. Choose whether to use customer managed keys or AWS owned keys carefully. Workspaces created with customer managed keys can't be converted to use AWS owned keys later (and vice versa). 1. (Optional) To add one or more tags to the workspace, choose **Add new tag**. Then, in **Key**, enter a name for the tag. You can add an optional value for the tag in **Value**. To add another tag, choose **Add new tag** again. 1. Choose **Create workspace**. The workspace details page appears. This displays information including the status, ARN, workspace ID, and endpoint URLs for this workspace for both remote write and queries. The status returns **CREATING** until the workspace is ready. Wait until the status is **ACTIVE** before you move on to setting up your metric ingestion. Make note of the URLs that are displayed for **Endpoint - remote write URL** and **Endpoint - query URL**. You'll need them when you configure your Prometheus server to remote write metrics to this workspace and when you query those metrics. For information about how to ingest metrics into the workspace, see [Ingest Prometheus metrics to the workspace](AMP-onboard-ingest-metrics.md). # Configure your workspace You can configure your workspace for the following: + Define *label sets* and define limits on the active time series that match your defined label sets. A label set is a set of one or more *labels*, which are name/value pairs that help give context to time series metrics. By defining label sets and setting active time series limits, you can limit spikes in one tenant or source to affect only that tenant or source. For example, if you set a 1,000,000 active time series limit on the label set `team=A env=prod`, then if the number of ingested time series that match that label set exceed the limit, then only the time series that match the label set are throttled. This way, other tenants or metric sources are unaffected. For more information about labels in Prometheus, see [Data Model](https://prometheus.io/docs/concepts/data_model/#data-model). + Set a retention period to define the number of days for the data to be retained in the workspace. **To configure your workspace** 1. Open the Amazon Managed Service for Prometheus console at [https://console.aws.amazon.com/prometheus/](https://console.aws.amazon.com/prometheus/home). 1. In the upper left corner of the page, choose the menu icon and then choose **All workspaces**. 1. Choose the **Workspace ID** of the workspace. 1. Choose the **Workspace configurations** tab. 1. To set the retention period for the workspace, choose **Edit** in the **Retention period** section. Then specify the new retention period in days. The maximum is 1095 days (three years). 1. To add or modify label sets and their active series limits, choose **Edit** in the **Label sets** section. Then do the following: 1. (Optional) Enter a value in **Default bucket limit** to set a limit on the maximum number of active time series that can be ingested in the workspace, counting only time series that don’t match any defined label set. 1. To define a label set, enter an active time series limit for the new label set under **Active series limit**. Then, enter a label and value for one label that will be used in the label set, and choose **Add label**. 1. (Optional) To define another label set, choose **Add another label set** and repeat the previous steps. 1. When you are finished, choose **Save changes**. # Edit a workspace alias You can edit a workspace to change its alias. To change the workspace alias using the AWS CLI, enter the following command. ``` aws amp update-workspace-alias --workspace-id my-workspace-id --alias "new-alias" ``` **To edit a workspace using the Amazon Managed Service for Prometheus console** 1. Open the Amazon Managed Service for Prometheus console at [https://console.aws.amazon.com/prometheus/](https://console.aws.amazon.com/prometheus/home). 1. In the upper left corner of the page, choose the menu icon and then choose **All workspaces**. 1. Choose the workspace ID of the workspace that you want to edit, and then choose **Edit**. 1. Enter a new alias for the workspace and then choose **Save**. # Find your Amazon Managed Service for Prometheus workspace details, including ARN You can find the details of your Amazon Managed Service for Prometheus workspace by using either the AWS console or the AWS CLI. ------ #### [ Console ] **To find your workspace details using the Amazon Managed Service for Prometheus console** 1. Open the Amazon Managed Service for Prometheus console at [https://console.aws.amazon.com/prometheus/](https://console.aws.amazon.com/prometheus/home). 1. In the upper left corner of the page, choose the menu icon and then choose **All workspaces**. 1. Choose the **Workspace ID** of the workspace. This will display details about your workspace, including: + **Current status** – The status of your workspace, for example **Active**, is displayed under **Status**. + **ARN** – The workspace ARN is displayed under **ARN**. + **ID** – The workspace ID is displayed under **Workspace ID**. + **URLs** – The console displays multiple URLs for the workspace, including the URLs for writing to or querying data from the workspace. **Note** By default, the URLs given are the IPv4 URLs. You can also use dualstack (IPv4 and IPv6 supported) URLs. These are the same, but are in the domain `api.aws` rather than the default `amazonaws.com`. For example, if you were to see the following (an IPv4 URL): ``` https://aps-workspaces.us-east-1.amazonaws.com/workspaces/ws-abcd1234-ef56-7890-ab12-example/api/v1/remote_write ``` You could create a dualstack (including support for IPv6), URL as follows: ``` https://aps-workspaces.us-east-1.api.aws/workspaces/ws-abcd1234-ef56-7890-ab12-example/api/v1/remote_write ``` Below this section are tabs with information about rules, alert manager, logs, configuration, and tags. ------ #### [ AWS CLI ] **To find your workspace details using the AWS CLI** The following command returns the details of the workspace. You must replace *my-workspace-id* with the workspace ID of the workspace for which you want the details. ``` aws amp describe-workspace --workspace-id my-workspace-id ``` This returns details about your workspace, including: + **Current status** – The status of your workspace, for example `ACTIVE`, is returned in the `statusCode` property. + **ARN** – The workspace ARN is returned in the `arn` property. + **URLs** – The AWS CLI returns the base URL for the workspace in the `prometheusEndpoint` property. **Note** By default, the URL returned is the IPv4 URL. You can also use a dualstack (IPv4 and IPv6 supported) URL in the domain `api.aws` rather than the default `amazonaws.com`. For example, if you were to see the following (an IPv4 URL): ``` https://aps-workspaces.us-east-1.amazonaws.com/workspaces/ws-abcd1234-ef56-7890-ab12-example/ ``` You could create a dualstack (including support for IPv6), URL as follows: ``` https://aps-workspaces.us-east-1.api.aws/workspaces/ws-abcd1234-ef56-7890-ab12-example/ ``` You can also create the remote write and query URLs for the workspace, by adding `/api/v1/remote_write` or `/api/v1/query`, respectively. ------ # Delete an Amazon Managed Service for Prometheus workspace Deleting a workspace deletes the data that has been ingested into it. **Note** Deleting an Amazon Managed Service for Prometheus workspace does not automatically delete any AWS managed collectors that are scraping metrics and sending them to the workspace. For more information, see [Find and delete scrapers](AMP-collector-how-to.md#AMP-collector-list-delete). **To delete a workspace using the AWS CLI** Use the following command: ``` aws amp delete-workspace --workspace-id my-workspace-id ``` **To delete a workspace using the Amazon Managed Service for Prometheus console** 1. Open the Amazon Managed Service for Prometheus console at [https://console.aws.amazon.com/prometheus/](https://console.aws.amazon.com/prometheus/home). 1. In the upper left corner of the page, choose the menu icon and then choose **All workspaces**. 1. Choose the workspace ID of the workspace that you want to delete, and then choose **Delete**. 1. Enter **delete** in the confirmation box, and choose **Delete**.