Setting up a friendly URL for OpenSearch UI applications (self-service)

To set up a friendly URL for your OpenSearch UI applications

1. Create a JSON file that maps your friendly names to application URLs. Each key becomes a subdomain (for example, key prod becomes https://prod.example.com).

   {
     "data": [
       {"key": "prod", "value": "https://application-prod-abc123.us-west-2.opensearch.amazonaws.com"},
       {"key": "staging", "value": "https://application-staging-def456.us-east-1.opensearch.amazonaws.com"},
       {"key": "analytics", "value": "https://application-analytics-ghi789.eu-west-1.opensearch.amazonaws.com"}
     ]
   }

   Save this file as opensearch-ui-friendly-url-app-mappings-v1.json. The v1 suffix identifies this as the first version of your mappings. You increment this version when you update your mappings.

2. Upload the mappings file to an Amazon S3 bucket in your account:

   aws s3 cp opensearch-ui-friendly-url-app-mappings-v1.json \
     s3://your-bucket-name/opensearch-ui-friendly-url-app-mappings-v1.json

3. Grant CloudFront permission to read the mappings file by adding a bucket policy. Replace your-bucket-name and your-account-id with your values:

   aws s3api put-bucket-policy \
     --bucket your-bucket-name \
     --policy '{
       "Version": "2012-10-17",
       "Statement": [{
         "Sid": "AllowCloudFrontKVSImport",
         "Effect": "Allow",
         "Principal": {"Service": "cloudfront.amazonaws.com"},
         "Action": "s3:GetObject",
         "Resource": "arn:aws:s3:::your-bucket-name/*",
         "Condition": {"StringEquals": {"aws:SourceAccount": "your-account-id"}}
       }]
     }'

   Note

   This bucket policy allows CloudFront to read the mappings file during KeyValueStore creation. Without it, stack deployment fails with a "SourceARN is inaccessible" error.

4. Deploy the CloudFormation stack using one of the following options:

   Option 1: Launch Stack (recommended)

   Copy the following URL and paste it into your browser to open the AWS CloudFormation quick-create page with the template pre-loaded. Fill in the parameters and choose Create stack.

   https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/quickcreate?templateURL=https://opensearch-ui-quickstart-sample-cfn-templates.s3.us-west-2.amazonaws.com/opensearch-ui-friendly-url/main.yaml&stackName=opensearch-ui-friendly-url&param_MappingsVersion=v1

   Option 2: AWS CLI

   Replace the placeholder values with your own:

   aws cloudformation create-stack \
     --stack-name opensearch-ui-friendly-url \
     --template-url https://opensearch-ui-quickstart-sample-cfn-templates.s3.us-west-2.amazonaws.com/opensearch-ui-friendly-url/main.yaml \
     --parameters \
       ParameterKey=DomainName,ParameterValue=your-domain.com \
       ParameterKey=HostedZoneId,ParameterValue=Z0123456789ABCDEFG \
       ParameterKey=MappingsBucket,ParameterValue=your-bucket-name \
       ParameterKey=MappingsKey,ParameterValue=opensearch-ui-friendly-url-app-mappings-v1.json \
       ParameterKey=MappingsVersion,ParameterValue=v1 \
     --region us-east-1

5. If you used the AWS CLI (Option 2), deploy the stack in the us-east-1 Region. CloudFront requires ACM certificates to be in us-east-1. Your OpenSearch UI applications can be in any Supported Regions and quotas for OpenSearch UI.

6. Wait for the stack to complete (approximately 15 minutes). You can monitor progress:

   aws cloudformation wait stack-create-complete \
     --stack-name opensearch-ui-friendly-url \
     --region us-east-1

7. Test the redirect. Open your browser and navigate to https://prod.your-domain.com. You should be redirected to your OpenSearch UI application.

   You can also verify with curl:

   curl -I https://prod.your-domain.com
   # Expected: HTTP/2 302
   # location: https://application-prod-abc123.us-west-2.opensearch.amazonaws.com

1. Edit your mappings file to add or remove entries. Save it with an incremented version suffix (for example, opensearch-ui-friendly-url-app-mappings-v2.json).

2. Upload the new version to S3:

   aws s3 cp opensearch-ui-friendly-url-app-mappings-v2.json \
     s3://your-bucket-name/opensearch-ui-friendly-url-app-mappings-v2.json

3. Update the stack with the new MappingsKey and MappingsVersion:

   Using the console: Open the CloudFormation console, select your stack, choose Update, select Use current template, then update the MappingsKey and MappingsVersion parameters with the new values.

   Using the AWS CLI:

   aws cloudformation update-stack \
     --stack-name opensearch-ui-friendly-url \
     --use-previous-template \
     --parameters \
       ParameterKey=DomainName,UsePreviousValue=true \
       ParameterKey=HostedZoneId,UsePreviousValue=true \
       ParameterKey=MappingsBucket,UsePreviousValue=true \
       ParameterKey=MappingsKey,ParameterValue=opensearch-ui-friendly-url-app-mappings-v2.json \
       ParameterKey=MappingsVersion,ParameterValue=v2 \
     --region us-east-1

To set up a friendly URL redirect without Route 53

1. Request a certificate in ACM

   1. Open the ACM console at https://console.aws.amazon.com/acm/ in the us-east-1 Region.

   2. Choose Request certificate.

   3. For Domain name, enter *.your-domain.com (wildcard certificate).

   4. For Validation method, choose DNS validation.

   5. Choose Request.

   6. On the certificate details page, note the CNAME record name and value under Domain validation. Create this CNAME record at your DNS provider to validate domain ownership.

   7. Wait for the certificate status to change to Issued (typically 5 to 30 minutes after DNS record creation).

2. Create a CloudFront KeyValueStore

   1. Open the CloudFront console at https://console.aws.amazon.com/cloudfront/.

   2. In the navigation pane, choose Functions. Then choose the KeyValueStores tab.

   3. Choose Create KeyValueStore.

   4. Enter a name (for example, opensearch-ui-friendly-url-app-mappings-store).

   5. Choose Create.

   6. After creation, choose Edit to add key-value pairs. For each application, add a key (the subdomain name, such as prod) and a value (the full OpenSearch UI application URL).

3. Create a CloudFront function

   1. Open the CloudFront console at https://console.aws.amazon.com/cloudfront/.

   2. In the navigation pane, choose Functions.

   3. On the Functions tab, choose Create function.

   4. Enter a name for the function (for example, opensearch-ui-friendly-url-redirect-function).

   5. For Runtime, choose cloudfront-js-2.0.

   6. Replace the function code with the following:

      import cf from 'cloudfront';
      
      const kvsHandle = cf.kvs("YOUR_KVS_ID");
      
      async function handler(event) {
        var request = event.request;
        var host = request.headers.host.value;
        var subdomain = host.split('.')[0];
      
        try {
          var targetUrl = await kvsHandle.get(subdomain);
          return {
            statusCode: 302,
            statusDescription: 'Found',
            headers: {
              'location': { value: targetUrl },
              'cache-control': { value: 'no-cache, no-store, must-revalidate' }
            }
          };
        } catch (e) {
          return {
            statusCode: 404,
            statusDescription: 'Not Found',
            headers: { 'content-type': { value: 'text/html' } },
            body: {
              encoding: 'text',
              data: '<html><body><h1>Application Not Found</h1><p>No OpenSearch application is mapped to the requested subdomain.</p></body></html>'
            }
          };
        }
      }

      Replace YOUR_KVS_ID with the ID of the KeyValueStore you created (visible on the KeyValueStore details page).

   7. In KeyValueStore associations, associate the KeyValueStore you created.

   8. Choose Save changes and then Publish function.

4. Create a CloudFront distribution

   1. In the CloudFront console, choose Create distribution.

   2. For Origin domain, enter any valid domain (for example, example.com). The origin is never contacted because the function returns a response before reaching it.

   3. Under Default cache behavior, for Viewer protocol policy, choose Redirect HTTP to HTTPS.

   4. For Cache policy, choose CachingDisabled.

   5. Under Function associations, for Viewer request, select your CloudFront function.

   6. Under Settings, for Alternate domain names (CNAMEs), enter *.your-domain.com.

   7. For Custom SSL certificate, select the certificate you created in ACM.

   8. Choose Create distribution.

   9. Note the distribution domain name (for example, d1234abcdef8.cloudfront.net).

5. Configure DNS at your provider

   At your DNS provider, create a CNAME record that points *.your-domain.com to your CloudFront distribution domain name (for example, d1234abcdef8.cloudfront.net).

   Note

   Some DNS providers don't support wildcard CNAME records. In that case, create individual CNAME records for each subdomain you want to use (for example, prod.your-domain.com, staging.your-domain.com).

1. Open the CloudFront console at https://console.aws.amazon.com/cloudfront/.

2. In the navigation pane, choose Functions. Then choose the KeyValueStores tab.

3. Choose your KeyValueStore name (for example, opensearch-ui-friendly-url-app-mappings-store).

4. Choose Edit.

5. Choose Add pair. Enter the subdomain name as the key and the full OpenSearch UI application URL as the value.

6. Choose Save changes.