From 9c58b252600a49012d4ac0f5c106f011c0907ef8 Mon Sep 17 00:00:00 2001 From: Trevor Bonas <45324987+trevorbonas@users.noreply.github.com> Date: Mon, 29 Apr 2024 15:14:48 -0700 Subject: [PATCH] Add documentation for API Gateway endpoints (#54) * Add documentation for API Gateway endpoints Documentation has been added covering what API Gateway endpoints are created via one-click deployment and what encryption in transit these endpoints use. * Fixing typo. Signed-off-by: forestmvey --------- Signed-off-by: forestmvey Co-authored-by: forestmvey --- README.md | 10 ++++++++-- serverless/DEVELOPER_README.md | 16 ++++++++++++++++ 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 813e41f..27dc21b 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,9 @@ The Prometheus Connector receives and sends time series data between Prometheus ## Quick Start +The following steps use one-click deployment to deploy the connector as a Lambda function along +with an API Gateway. + 1. [Prerequisites](#prerequisites) are met. 2. [Prometheus is configured](#prometheus-configuration), minimum version `2.0.0`. 3. Deploy with one click deployment: [serverless/DEVELOPER_README.md#deployment](serverless/DEVELOPER_README.md#deployment). @@ -662,8 +665,11 @@ remote_read: ## Authentication -The Prometheus Connector will use the default credentials provider implemented in the AWS SDK for Go instead of allowing users -to provide the credentials through command-line flags. This prevents sensitive data from being easily scraped. +When the connector is deployed as a Lambda function, authentication is handled by passing through credentials with each request; validation is done within the Lambda function using the AWS SDK for Go. In general, the Timestream Prometheus Connector will use the default credentials provider implemented in the AWS SDK for Go instead of allowing users to provide the credentials through command-line flags. This prevents sensitive data from being easily scraped. + +Due to Prometheus' lack of support for SigV4 (see the [Unsupported SigV4 Authentication](#unsupported-sigv4-authentication) section), the +API Gateway deployed via one-click deployment or with the `serverless/template.yml` CloudFormation template +does not use SigV4 for its public endpoints. ## User-Agent Header diff --git a/serverless/DEVELOPER_README.md b/serverless/DEVELOPER_README.md index 3922dd9..b9ffd95 100644 --- a/serverless/DEVELOPER_README.md +++ b/serverless/DEVELOPER_README.md @@ -39,6 +39,10 @@ To start using the Prometheus remote storage connector for Timestream, there are ### One-click Deployment +One-click deployment will deploy the connector as a Lambda function along with an API Gateway. +The API Gateway will use a public endpoint with TLS 1.2 encryption for requests. +For more information on the API Gateway's public endpoints, see the [Amazon API Gateway Public Endpoints](#amazon-api-gateway-public-endpoints) section below. + Use an [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) [template](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-whatis-concepts.html#cfn-concepts-templates) to create the [stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-whatis-concepts.html#cfn-concepts-stacks): To install the Timestream Prometheus Connector service launch the AWS CloudFormation stack on the AWS CloudFormation console by choosing one of the "Launch Stack" buttons in the following table: @@ -215,6 +219,18 @@ Follow the verification steps in [README.md#verification](../README.md#verificat The default stage name `dev` may indicate the endpoint is at `development` stage. If the application is ready for production, set the stage name to a more appropriate value like `prod` when deploying the stack. +### Amazon API Gateway Public Endpoints + +When deployed with one-click deployment or the `serverless/template.yml` CloudFormation template, an API Gateway will be created with public endpoints. + +The public endpoints are: + +- Write: `https://.execute-api..amazonaws.com/dev/write` + +- Read: `https://.execute-api..amazonaws.com/dev/read` + +The public endpoints use a minimum of TLS 1.2 encryption in transit for all requests, as all API Gateway endpoints do [by default](https://docs.aws.amazon.com/apigateway/latest/developerguide/data-protection-encryption.html#data-protection-in-transit). + ## Required Permissions The template assumes the user deploying the project has all the required permissions. If the user is missing any of the required permissions the deployment will fail.