diff --git a/docs/config.json b/docs/config.json index 2e36abe38b79c..260babb8b0c5d 100644 --- a/docs/config.json +++ b/docs/config.json @@ -1178,6 +1178,10 @@ "title": "AWS Redshift Serverless", "slug": "/database-access/guides/redshift-serverless/" }, + { + "title": "AWS OpenSearch", + "slug": "/database-access/guides/aws-opensearch/" + }, { "title": "Azure Cache for Redis", "slug": "/database-access/guides/azure-redis/" diff --git a/docs/cspell.json b/docs/cspell.json index 41a67b262914c..6c2ea46922b64 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -9,7 +9,6 @@ "AICPA’s", "AKIA", "AMAZ", - "anonymization", "ANPAW", "APPDATA", "APPSECRET", @@ -19,24 +18,19 @@ "AWSIIDTTL", "Addrs", "Afax", - "apimachinery", "Aqxs", "Archlinux", "Authy", - "authteleportconfig", "BDRVJUSUZ", "BSFD", "BUCKETNAME", "Binm", + "Brosnan", "CAcreateserial", "CCDC", "CHANGEID", "CHANGEME", - "chartmode", - "clientcmd", "CLOUDSDK", - "clusterrolebindings", - "clusterroles", "CTAP", "Cgajq", "DBSIZE", @@ -44,14 +38,12 @@ "DHDR", "DQMB", "DSID", - "deanonymize", "Decisiv", "Deeplink", "Dfnnpu", "Dfumu", "Distroless", "Divio's", - "dtypes", "ECMWF", "ERRO", "Elastcsearch", @@ -74,8 +66,6 @@ "Goland", "Grafana's", "Gtczk", - "hostdb", - "hsm-ppzzfxbleki", "HSTS", "Hqlo", "IAMR", @@ -90,8 +80,8 @@ "Instruqt", "Intelli", "Iqxtr", - "JDBC", "JCRP", + "JDBC", "JWTs", "JYAUAA", "Jetstack", @@ -105,13 +95,8 @@ "Kubes", "LDAPS", "LOCALAPPDATA", - "lsnrctl", - "machineidnote", - "memlock", - "mlockall", "MAINPID", "MDAs", - "metav", "MGET", "MYDNS", "MYELB", @@ -147,11 +132,8 @@ "Pbbd", "Pluggable", "Println", - "proxyteleportconfig", "Quickstart", "Quicktime's", - "rabbitmq", - "rbacv", "REDISCLI", "REPLCONF", "REPLICAOF", @@ -159,7 +141,6 @@ "Rdik", "Relogging", "Relogin", - "rolebindings", "SAMLIDP", "SECURITYADMIN", "SIEM", @@ -173,18 +154,13 @@ "Sllavd", "Smartcard", "Sprintf", - "sqlcl", - "sqlnet", "Stackdriver", - "structs", - "strslice", "Svhk", "Swic", "Swicm", "TCPS", "TELEPORTING", "TENANTID", - "thred", "TOTP", "TOUCHID", "Tele", @@ -192,8 +168,6 @@ "Tmkx", "Toboth", "Traefik", - "updaterreleasechannel", - "updaterversionserver", "Upsert", "Upserted", "Uwhp", @@ -230,8 +204,10 @@ "allkeys", "allowdeny", "allowedlogins", + "anonymization", "anotheruser", "apikey", + "apimachinery", "apiserver", "appdomain", "appuser", @@ -249,6 +225,7 @@ "authserver", "authserver", "authservers", + "authteleportconfig", "authz", "autodiscovery", "automount", @@ -276,14 +253,16 @@ "centralus", "certificatekey", "certutil", - "cfsdf", "cfhunter", + "cfsdf", "cgroupv", "chacha", + "chartmode", "cicd", "cimg", "ciphersuites", "circleci", + "clientcmd", "clientid", "clis", "cloudbuild", @@ -297,6 +276,8 @@ "clusterolebinding", "clusterrole", "clusterrolebinding", + "clusterrolebindings", + "clusterroles", "cockroachdb", "codingllama", "cond", @@ -318,6 +299,7 @@ "dbgroup", "dbname", "dbuser", + "deanonymize", "deregisters", "devel", "develnode", @@ -333,6 +315,7 @@ "dronegen", "dsacls", "dspublish", + "dtypes", "dualstack", "dylib", "dynamicappregexample", @@ -397,9 +380,11 @@ "highavailability", "highavailabilitycertmanager", "hostcert", + "hostdb", "hostedzone", "hostip", "hostssl", + "hsm-ppzzfxbleki", "httpout", "iamserviceaccount", "idps", @@ -457,8 +442,10 @@ "loginwithmsft", "logrus", "lptne", + "lsnrctl", "lucidchart", "machineid", + "machineidnote", "mactor", "mallocs", "managedclusters", @@ -467,13 +454,16 @@ "masteruser", "mattermosttokenfromsecret", "mcache", + "memlock", "memorydb", "memstats", "mermaidjs", + "metav", "microk", "minikube", "minikube's", "mlock", + "mlockall", "mongodbatlas", "mongosh", "mpghq", @@ -542,6 +532,8 @@ "onelogin", "oneshot", "onmicrosoft", + "opensearch", + "opensearchsql", "operatorenabled", "opsexample", "organisation", @@ -572,6 +564,7 @@ "proxyaddr", "proxying", "proxylistenermode", + "proxyteleportconfig", "pseudoversion", "psql", "pstree", @@ -579,10 +572,13 @@ "ptrace", "pwgen", "quicktime", + "rabbitmq", + "rbacv", "rdbms", "rdns", "rdsca", "rdsproxy", + "readall", "readyz", "realmd", "reauthentication", @@ -600,6 +596,7 @@ "roadmap", "rolearn", "rolebinding", + "rolebindings", "rollouts", "rootcluster", "rtrzn", @@ -634,6 +631,8 @@ "splunkd", "splunkd", "splunkforwarder", + "sqlcl", + "sqlnet", "sqlserver", "sshcacerts", "sshcert", @@ -641,6 +640,8 @@ "starttls", "statefulset", "storageenabled", + "strslice", + "structs", "subkind", "sudoer", "syscalls", @@ -661,6 +662,7 @@ "tenantname", "testuser", "thisisunsafe", + "thred", "timechart", "tlscacerts", "tlscert", @@ -683,6 +685,8 @@ "unmarshal", "unprefixed", "unregistering", + "updaterreleasechannel", + "updaterversionserver", "uqcje", "urandom", "userdel", diff --git a/docs/img/database-access/guides/aws-opensearch/01-opensearch_get_started.png b/docs/img/database-access/guides/aws-opensearch/01-opensearch_get_started.png new file mode 100644 index 0000000000000..110b3f313c548 Binary files /dev/null and b/docs/img/database-access/guides/aws-opensearch/01-opensearch_get_started.png differ diff --git a/docs/img/database-access/guides/aws-opensearch/02-opensearch_mapped_users.png b/docs/img/database-access/guides/aws-opensearch/02-opensearch_mapped_users.png new file mode 100644 index 0000000000000..b35ee4154b51f Binary files /dev/null and b/docs/img/database-access/guides/aws-opensearch/02-opensearch_mapped_users.png differ diff --git a/docs/img/database-access/guides/aws-opensearch/03-opensearch_iam_role_mapping.png b/docs/img/database-access/guides/aws-opensearch/03-opensearch_iam_role_mapping.png new file mode 100644 index 0000000000000..1a3c544e12dc8 Binary files /dev/null and b/docs/img/database-access/guides/aws-opensearch/03-opensearch_iam_role_mapping.png differ diff --git a/docs/img/database-access/guides/aws-opensearch/create-ec2-role.png b/docs/img/database-access/guides/aws-opensearch/create-ec2-role.png new file mode 100644 index 0000000000000..8e3621a87a548 Binary files /dev/null and b/docs/img/database-access/guides/aws-opensearch/create-ec2-role.png differ diff --git a/docs/img/database-access/guides/aws-opensearch/create-role-1.png b/docs/img/database-access/guides/aws-opensearch/create-role-1.png new file mode 100644 index 0000000000000..2cf1e7cd8ef74 Binary files /dev/null and b/docs/img/database-access/guides/aws-opensearch/create-role-1.png differ diff --git a/docs/img/database-access/guides/aws-opensearch/opensearch_cloud.png b/docs/img/database-access/guides/aws-opensearch/opensearch_cloud.png new file mode 100644 index 0000000000000..14d4859717079 Binary files /dev/null and b/docs/img/database-access/guides/aws-opensearch/opensearch_cloud.png differ diff --git a/docs/img/database-access/guides/aws-opensearch/opensearch_selfhosted.png b/docs/img/database-access/guides/aws-opensearch/opensearch_selfhosted.png new file mode 100644 index 0000000000000..71d674fcc23de Binary files /dev/null and b/docs/img/database-access/guides/aws-opensearch/opensearch_selfhosted.png differ diff --git a/docs/pages/database-access/guides/aws-opensearch.mdx b/docs/pages/database-access/guides/aws-opensearch.mdx new file mode 100644 index 0000000000000..7e1e616794788 --- /dev/null +++ b/docs/pages/database-access/guides/aws-opensearch.mdx @@ -0,0 +1,359 @@ +--- +title: Database Access with AWS OpenSearch +description: How to access AWS OpenSearch with Teleport database access +--- + +Access to AWS OpenSearch can be provided by [Teleport Database +Access](../introduction.mdx). This allows for +fine-grain access control through [Teleport's RBAC](../../database-access/rbac.mdx). + +This guide will help you to: + +- Install the Teleport Database Service. +- Set up the Teleport Database Service to access AWS OpenSearch Service via REST API. +- Connect to your AWS OpenSearch Service through the Teleport Database Service. + + +![OpenSearch Self-Hosted](../../../img/database-access/guides/aws-opensearch/opensearch_selfhosted.png) + + +![OpenSearch Cloud](../../../img/database-access/guides/aws-opensearch/opensearch_cloud.png) + + +## Prerequisites + +- AWS OpenSearch domain. +- [Enabled AWS OpenSearch Service fine-grained access + control](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html#fgac-enabling) +- IAM permissions to create IAM roles. +- [opensearchsql](https://github.com/opensearch-project/sql-cli) Command Line + Interface (CLI) tool installed in `$PATH`. + +(!docs/pages/includes/edition-prereqs-tabs.mdx!) + +- A host, e.g., an EC2 instance, where you will run the Teleport Database Service. + This guide assumes an EC2 instance when creating and applying IAM roles, and + must be adjusted accordingly for custom configurations. +- (!docs/pages/includes/tctl.mdx!) + + +This guide provides an example configuration of IAM access roles as a model, +and uses an EC2 instance to serve the Teleport Database Service. The level of +access provided may not suit your needs, or may not fit your organization's +access conventions. You should adjust the AWS IAM permissions to fit your needs. + + +## Step 1/4. Create IAM roles for OpenSearch Managed Cluster access + +The setup described in this guide requires two IAM roles: +- One associated with the EC2 instance running the Teleport Database Service, + which lets it assume additional roles granted to the user. +- One that can be assumed by the EC2 instance role and grants access to OpenSearch + manage cluster to users. + +### EC2 instance role + +Visit the [IAM > Roles page](https://console.aws.amazon.com/iamv2/home#/roles) of +the AWS Console, then press "Create Role". Under **Trusted entity type** select +"AWS service". Under **Use case** select "EC2", then click **Next**. + +![Create Role to Identify EC2 Instance](../../../img/database-access/guides/aws-opensearch/create-ec2-role.png) + +On the "Add Permissions" page, you can simply click **Next** since this role +does not require any permissions. In this guide, we will use the example name +`TeleportDatabaseService` for this role. Once you have chosen a name, click +**Create Role** to complete the process. + +### OpenSearch Mange Cluster access role + +Navigate back to the Roles page and create a new role. Select the "AWS account" +option, which creates a default trust policy to allow other entities in this +account to assume this role: + +![Create Role Step 1](../../../img/database-access/guides/aws-opensearch/create-role-1.png) + +Click **Next**. On the next page, enter a role name. In this guide we'll use +the example name `ExampleTeleportOpenSearchRole` for this role. + +Under "Select trusted entities", update the JSON to allow the `TeleportDatabaseService` +role to assume this role: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": [ + "arn:aws:iam::(=aws.aws_access_key=):role/TeleportDatabaseService" + ] + }, + "Action": "sts:AssumeRole", + "Condition": {} + } + ] +} +``` + +Finally, click **Create Role**. + +### Configure Cluster Fine-grained access control IAM Role mapping in Amazon OpenSearch Managed Custer + +Teleport AWS OpenSearch service integration leverages the [OpenSearch Fine-grained +access control](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html) +where the IAM role or user is mapped to the OpenSearch role. + +In order to configure Role Mapping log into OpenSearch Domain Dashboard using +the master user and go to the `Security` settings: + +![Select Get Started](../../../img/database-access/guides/aws-opensearch/01-opensearch_get_started.png) + +Create a new role with least privilege permissions, or select an existing one. +For the purpose of this example the `readall` OpenSearch role will be used. +Select the OpenSearch role and go to the `Mapped users` tab: + +![Mapped User](../../../img/database-access/guides/aws-opensearch/02-opensearch_mapped_users.png) + +Add mapping between the OpenSearch role and AWS IAM `ExampleTeleportOpenSearchRole` +role created in the previous step. + +![IAM Role mapping](../../../img/database-access/guides/aws-opensearch/03-opensearch_iam_role_mapping.png) + +Finally, click the **Map** button to apply the settings. + +## Step 2/4. Configure the Teleport IAM role mapping + +The next step is to give your Teleport users permissions to assume AWS IAM roles +when accessing AWS resources through your Teleport cluster. + +You can do this by creating a Teleport role with the `db_users` field +listing the IAM role ARN created in the previous step. Create a file called +`aws-opensearch-access.yaml` with the following content: + +```yaml +kind: role +version: v6 +metadata: + name: aws-opensearch-access +spec: + allow: + db_labels: + 'env': 'dev' + db_users: + - 'ExampleTeleportOpenSearchRole' +``` + +Create the new role: + +```code +$ tctl create -f aws-opensearch-access.yaml +``` + +(!docs/pages/includes/add-role-to-user.mdx role="aws-opensearch-access"!) + +## Step 3/4. Install the Teleport Database Service + +Create an EC2 instance to host the Teleport Database Service, and attach the +`TeleportDatabaseService` AWS IAM role to it. If you're hosting the service another +way, you must provide AWS credentials to the service - see [AWS credentials +configuration](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html) +for more details. + + +For non-standard AWS regions such as AWS GovCloud (US) regions and AWS China +regions, please set the corresponding region in the `AWS_REGION` environment +variable or in the AWS credentials file so that the Database Service can use +the correct STS endpoint. + + +### Generate a token + +
+ +For users with a lot of infrastructure in AWS, or who might create or recreate +many instances, consider alternative methods for joining new EC2 instances running +Teleport: + +- [Configure Teleport to Automatically Enroll EC2 instances (Preview)](../../server-access/guides/ec2-discovery.mdx) +- [Joining Nodes via AWS IAM + Role](../../management/join-services-to-your-cluster/aws-iam.mdx) +- [Joining Nodes via AWS EC2 Identity Document](../../management/join-services-to-your-cluster/aws-ec2.mdx) + +
+ +(!docs/pages/includes/database-access/token.mdx!) + +Use the token provided by the output of this command in the next step. + +### Install and start Teleport + +Install Teleport on the host where you will run the Teleport Database +Service. See our [Installation](../../installation.mdx) page for options +besides Linux servers. + +(!docs/pages/includes/install-linux.mdx!) + + + + +On the host where you will run the Teleport Database Service, start Teleport +with the appropriate configuration. + +Note that a single Teleport process can run multiple different services, for +example multiple Database Service agents as well as the SSH Service or Application +Service. The step below will overwrite an existing configuration file, so if +you're running multiple services add `--output=stdout` to print the config in +your terminal, and manually adjust `/etc/teleport.yaml`. + +Generate a configuration file at `/etc/teleport.yaml` for the Database Service: + +```code +$ teleport db configure create \ + -o file \ + --token=/tmp/token \ + --proxy= \ + --name=example-opensearch \ + --protocol=opensearch \ + --uri=your-opensearch-domain-url.eu-central-1.es.amazonaws.com:443 \ + --aws-account-id=(=aws.aws_access_key=) \ + --labels=env=dev +``` + + + + +On the host where you will run {{ service }}, start Teleport: + +```code +$ sudo systemctl enable teleport +$ sudo systemctl start teleport +``` + + + + +On the host where you will run {{ service }}, create a systemd service +configuration for Teleport, enable the Teleport service, and start Teleport: + +```code +$ sudo teleport install systemd -o /etc/systemd/system/teleport.service +$ sudo systemctl enable teleport +$ sudo systemctl start teleport +``` + + + + + + + +Modify your Teleport Database Service static configuration file: + +```yaml +db_service: + enabled: "yes" + databases: + - name: example-opensearch + aws: + account_id: "(=aws.aws_access_key=)" + protocol: opensearch + uri: your-opensearch-domain-url.eu-central-1.es.amazonaws.com:443 + static_labels: + env: dev +``` + +Restart the Teleport Database Service for the configuration file changes to take +effect. + + + +Create a dynamic database resource to dynamically register an AWS database +in an external account and proxy connections to it. + +```yaml +kind: db +version: v3 +metadata: + name: "example-opensearch" + description: "Example dynamic database resource" + labels: + env: "dev" +spec: + protocol: "opensearch" + uri: your-opensearch-domain-url.eu-central-1.es.amazonaws.com:443 + aws: + account_id: "(=aws.aws_access_key=)" +``` + +Save the configuration to a file like `database.yaml` and create it with `tctl`: + +```code +$ tctl create database.yaml +``` + +For more information about database registration using dynamic database +resources, see: [Dynamic Registration](dynamic-registration.mdx). + + + + +## Step 4/4. Connect + +Once the Database Service has started and joined the cluster, you can start accessing AWS OpenSearch API: + +Create a proxy tunnel: + +```code +$ tsh proxy db --tunnel --port=8000 --db-user=ExampleTeleportOpenSearchRole example-opensearch +Started authenticated tunnel for the OpenSearch database "example-opensearch" in cluster "teleport.example.com" on 127.0.0.1:8000. + +Use one of the following commands to connect to the database or to the address above using other database GUI/CLI clients: + + * start interactive session with opensearchsql: + + $ opensearchsql http://localhost:8000 + + * run request with opensearch-cli: + + $ opensearch-cli --profile teleport --config /Users/alice/.tsh/teleport.example.dev/example-opensearch/opensearch-cli/8a5ce249.yml curl get --path / + + * run request with curl: + + $ curl http://localhost:8000/ +``` + +You can now interact with AWS OpenSearch API via local tunnel created by the `tsh proxy db` command: + +```code +$ curl http://localhost:8000/movies/_search \ + -H 'Content-Type: application/json' \ + -d '{ "query": { "match_all": {} } }' + +{"took":170,"timed_out":false,"_shards":{"total":5,"successful":5,"skipped":0,"failed":0},"hits":{"total":{"value":1,"relation":"eq"},"max_score":1.0,"hits":[{"_index":"movies","_id":"1","_score":1.0,"_source":{"director": "Burton, Tim", "genre": ["Comedy","Sci-Fi"], "year": 1996, "actor": ["Jack Nicholson","Pierce Brosnan","Sarah Jessica Parker"], "title": "Mars Attacks!"}}]}} +``` + +Interactive session can be started using the `tsh db connect` command, which invokes the `opensearchsql` binary with interactive mode under the hood: + +```code +$ tsh db connect example-opensearch --db-user=ExampleTeleportOpenSearchRole +# ____ _____ __ +# / __ \____ ___ ____ / ___/___ ____ ___________/ /_ +# / / / / __ \/ _ \/ __ \\__ \/ _ \/ __ `/ ___/ ___/ __ \ +#/ /_/ / /_/ / __/ / / /__/ / __/ /_/ / / / /__/ / / / +#\____/ .___/\___/_/ /_/____/\___/\__,_/_/ \___/_/ /_/ +# /_/ +# +#Server: OpenSearch 2.5.0 +#CLI Version: 1.0.0 +#Endpoint: http://localhost:56766 +#Query Language: sql +opensearchsql> select * from movies; +#fetched rows / total rows = 1/1 +#+----------------+---------+---------------+--------+-------------+ +#| actor | genre | title | year | director | +#|----------------+---------+---------------+--------+-------------| +#| Jack Nicholson | Comedy | Mars Attacks! | 1996 | Burton, Tim | +#+----------------+---------+---------------+--------+-------------+ +opensearchsql> +``` \ No newline at end of file diff --git a/docs/pages/includes/database-access/guides.mdx b/docs/pages/includes/database-access/guides.mdx index bb16a53595354..532000f88a04a 100644 --- a/docs/pages/includes/database-access/guides.mdx +++ b/docs/pages/includes/database-access/guides.mdx @@ -3,6 +3,7 @@ - [Active Directory SQL Server (Preview)](../../database-access/guides/sql-server-ad.mdx): Connect Microsoft SQL Server with Active Directory authentication. - [Active Directory SQL Server with PKINIT (Preview)](../../database-access/guides/sql-server-ad-pkinit.mdx): Connect Microsoft SQL Server with Active Directory PKINIT authentication. - [AWS DynamoDB](../../database-access/guides/aws-dynamodb.mdx): Connect AWS DynamoDB. +- [AWS OpenSearch](../../database-access/guides/aws-opensearch.mdx): Connect AWS OpenSearch. - [AWS ElastiCache & MemoryDB](../../database-access/guides/redis-aws.mdx): Connect AWS ElastiCache or AWS MemoryDB for Redis database. - [AWS RDS & Aurora](../../database-access/guides/rds.mdx): Connect AWS RDS or Aurora PostgreSQL, MariaDB or MySQL database. - [AWS RDS Proxy](../../database-access/guides/rds-proxy.mdx): Connect AWS RDS Proxy instances to Teleport.