Configurando um URL amigável para aplicativos de OpenSearch interface do usuário (autoatendimento)

OpenSearch Os aplicativos de interface do usuário têm URLs gerados automaticamente, como. https://application-name-id.Region.opensearch.amazonaws.com Esses URLs são longos e difíceis de lembrar. Você pode configurar um URL amigável (comohttps://prod.example.com). Esse URL redireciona para seu aplicativo, para que você possa acessar os painéis diretamente sem precisar navegar pelo Management Console. AWS

Como funciona

Essa solução é usada CloudFront para redirecionar solicitações do seu URL amigável para o endpoint do aplicativo de OpenSearch interface do usuário. A arquitetura consiste nos seguintes componentes:

• Certificado ACM — Fornece criptografia HTTPS para sua URL amigável.

• CloudFront KeyValueStore— Armazena o mapeamento entre nomes de subdomínios e URLs de aplicativos.

• CloudFront função — Lê KeyValueStore e retorna um redirecionamento 302 para a URL correta do aplicativo.

• CloudFront distribuição — Serve seu URL amigável com TLS e encaminha as solicitações por meio da função.

• Registro DNS do Route 53 — aponta seu URL amigável para a CloudFront distribuição.

Quando você visita seu URL amigável (por exemplo,https://prod.example.com), a CloudFront função procura o URL do aplicativo correspondente e redireciona seu navegador para ele. O aplicativo lida diretamente com a autenticação.

Pré-requisitos

• Um ou mais aplicativos de OpenSearch interface do usuário com seus URLs de endpoint.

• Um nome de domínio que você possui (por exemplo,example.com).

• Uma zona pública hospedada no Route 53 para seu domínio. Se você não tiver um, para obter mais informações, consulteConfiguração sem o Route 53 (configuração manual).

• Um bucket do Amazon S3 para armazenar o arquivo de mapeamento de URL do seu aplicativo.

Implante usando AWS CloudFormation

Use o procedimento a seguir para implantar a infraestrutura amigável de redirecionamento de URL com um CloudFormation modelo.

Para configurar um URL amigável para seus aplicativos de OpenSearch interface do usuário

1. Crie um arquivo JSON que mapeie seus nomes amigáveis para URLs de aplicativos. Cada chave se torna um subdomínio (por exemplo, chave prod se tornahttps://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"}
     ]
   }

   Salve esse arquivo como opensearch-ui-friendly-url-app-mappings-v1.json. O v1 sufixo identifica isso como a primeira versão dos seus mapeamentos. Você incrementa essa versão ao atualizar seus mapeamentos.

2. Faça o upload do arquivo de mapeamento para um bucket do Amazon S3 em sua conta:

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

3. Conceda CloudFront permissão para ler o arquivo de mapeamento adicionando uma política de bucket. your-bucket-nameyour-account-idSubstitua e por seus valores:

   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"}}
       }]
     }'

   nota

   Essa política de bucket CloudFront permite ler o arquivo de mapeamento durante a KeyValueStore criação. Sem isso, a implantação da pilha falha com o erro “sourceARN está inacessível”.

4. Implante a CloudFormation pilha usando uma das seguintes opções:

   Opção 1: Launch Stack (recomendado)

   Copie o URL a seguir e cole-o em seu navegador para abrir a página de AWS CloudFormation criação rápida com o modelo pré-carregado. Preencha os parâmetros e escolha Criar pilha.

   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

   Opção 2: AWS CLI

   Substitua os valores do espaço reservado pelos seus próprios:

   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. Se você usou a AWS CLI (Opção 2), implante a pilha na us-east-1 região. CloudFront exige que os certificados ACM estejam presentesus-east-1. Seus aplicativos de OpenSearch interface de usuário podem estar em qualquer região com suporte e cotas de OpenSearch interface do usuário.

6. Aguarde a conclusão da pilha (aproximadamente 15 minutos). Você pode monitorar o progresso:

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

7. Teste o redirecionamento. Abra seu navegador e navegue atéhttps://prod.your-domain.com. Você deve ser redirecionado para seu aplicativo de OpenSearch interface do usuário.

   Você também pode verificar comcurl:

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

CloudFormation fonte do modelo

Veja a seguir o CloudFormation modelo completo usado pelo link do Launch Stack e pelo comando CLI acima. Você também pode baixá-lo diretamente dehttps://opensearch-ui-quickstart-sample-cfn-templates.s3.us-west-2.amazonaws.com/opensearch-ui-friendly-url/main.yaml.

AWSTemplateFormatVersion: '2010-09-09'
Metadata:
  TemplateVersion: '1.0.0'
  LastUpdated: '2026-08-05'
  Author: 'OpenSearch UI Team'
Description: >
  OpenSearch UI Friendly URL - Creates a CloudFront distribution with a CloudFront Function
  that redirects friendly subdomain URLs to OpenSearch Application endpoints.
  Deploy this template in us-east-1 (required for ACM certificates used with CloudFront).

Parameters:
  DomainName:
    Type: String
    Description: "Your domain name (e.g., example.com or subdomain.example.com)"
    AllowedPattern: "^[a-zA-Z0-9][a-zA-Z0-9-]*(\\.[a-zA-Z0-9][a-zA-Z0-9-]*)+$"
  HostedZoneId:
    Type: AWS::Route53::HostedZone::Id
    Description: "Route 53 Hosted Zone ID for your domain"
  MappingsBucket:
    Type: String
    Description: "S3 bucket name containing your app mappings JSON file"
  MappingsKey:
    Type: String
    Description: "S3 key (path) to your app mappings JSON file"
    Default: "opensearch-ui-friendly-url-app-mappings.json"
  MappingsVersion:
    Type: String
    Description: "Version identifier for your mappings (change this when updating mappings, e.g., v1, v2, v3)"
    Default: "v1"
    AllowedPattern: "^[a-zA-Z0-9-]+$"

Resources:
  # 1. Wildcard TLS Certificate (DNS validated via Route 53)
  Certificate:
    Type: AWS::CertificateManager::Certificate
    Properties:
      DomainName: !Sub "*.${DomainName}"
      ValidationMethod: DNS
      DomainValidationOptions:
        - DomainName: !Sub "*.${DomainName}"
          HostedZoneId: !Ref HostedZoneId

  # 2. CloudFront KeyValueStore with S3 import for app mappings
  AppMappingStore:
    Type: AWS::CloudFront::KeyValueStore
    Properties:
      Name: !Sub "${AWS::StackName}-kvs-${MappingsVersion}"
      Comment: !Sub "OpenSearch UI app mappings ${MappingsVersion} for ${DomainName}"
      ImportSource:
        SourceType: S3
        SourceArn: !Sub "arn:aws:s3:::${MappingsBucket}/${MappingsKey}"

  # 3. CloudFront Function (reads KVS, returns 302 redirect)
  RedirectFunction:
    Type: AWS::CloudFront::Function
    Properties:
      Name: !Sub "${AWS::StackName}-fn"
      AutoPublish: true
      FunctionConfig:
        Comment: !Sub "Redirects friendly URLs to OpenSearch Application endpoints (${MappingsVersion})"
        Runtime: cloudfront-js-2.0
        KeyValueStoreAssociations:
          - KeyValueStoreARN: !GetAtt AppMappingStore.Arn
      FunctionCode: !Sub |
        import cf from 'cloudfront';

        const kvsHandle = cf.kvs("${AppMappingStore.Id}");

        async function handler(event) {
          var request = event.request;
          var host = request.headers.host.value;
          
          // Extract subdomain prefix (e.g., "app1" from "app1.example.com")
          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) {
            // Key not found - return 404
            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>'
              }
            };
          }
        }

  # 4. CloudFront Distribution
  Distribution:
    Type: AWS::CloudFront::Distribution
    DependsOn: Certificate
    Properties:
      DistributionConfig:
        Enabled: true
        Comment: !Sub "OpenSearch UI Friendly URL for ${DomainName}"
        Aliases:
          - !Sub "*.${DomainName}"
        ViewerCertificate:
          AcmCertificateArn: !Ref Certificate
          SslSupportMethod: sni-only
          MinimumProtocolVersion: TLSv1.2_2021
        DefaultCacheBehavior:
          ViewerProtocolPolicy: redirect-to-https
          AllowedMethods:
            - GET
            - HEAD
          CachedMethods:
            - GET
            - HEAD
          CachePolicyId: "4135ea2d-6df8-44a3-9df3-4b5a84be39ad"  # AWS managed CachingDisabled policy
          TargetOriginId: dummy-origin
          FunctionAssociations:
            - EventType: viewer-request
              FunctionARN: !GetAtt RedirectFunction.FunctionMetadata.FunctionARN
        Origins:
          - Id: dummy-origin
            DomainName: "example.com"
            CustomOriginConfig:
              OriginProtocolPolicy: https-only
        HttpVersion: http2and3
        IPV6Enabled: true
        PriceClass: PriceClass_All

  # 5. Wildcard DNS record pointing to CloudFront
  WildcardDnsRecord:
    Type: AWS::Route53::RecordSet
    Properties:
      HostedZoneId: !Ref HostedZoneId
      Name: !Sub "*.${DomainName}"
      Type: A
      AliasTarget:
        HostedZoneId: Z2FDTNDATAQYW2  # CloudFront's fixed hosted zone ID (constant for all distributions)
        DNSName: !GetAtt Distribution.DomainName
        EvaluateTargetHealth: false

Outputs:
  CloudFrontDomain:
    Description: "CloudFront distribution domain name"
    Value: !GetAtt Distribution.DomainName
  CertificateArn:
    Description: "ACM Certificate ARN"
    Value: !Ref Certificate
  KeyValueStoreArn:
    Description: "CloudFront KeyValueStore ARN"
    Value: !GetAtt AppMappingStore.Arn
  ExampleUrl:
    Description: "Example friendly URL"
    Value: !Sub "https://prod.${DomainName}"
  MappingsFileLocation:
    Description: "S3 location of your app mappings file"
    Value: !Sub "s3://${MappingsBucket}/${MappingsKey}"
  CurrentMappingsVersion:
    Description: "Current mappings version deployed"
    Value: !Ref MappingsVersion
  TemplateVersion:
    Description: "Template version and last updated date"
    Value: "1.0.0 (2026-08-05)"

Adicionar ou remover aplicativos

Para adicionar, atualizar ou remover mapeamentos de aplicativos, crie uma nova versão do seu arquivo de mapeamento do S3 e atualize a pilha com a nova versão. A abordagem versionada mantém seu arquivo S3 como a fonte da verdade e permite que você avance para novas configurações ou reverta para versões anteriores a qualquer momento.

1. Edite seu arquivo de mapeamento para adicionar ou remover entradas. Salve-o com um sufixo de versão incrementado (por exemplo,opensearch-ui-friendly-url-app-mappings-v2.json).

2. Faça o upload da nova versão para o 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. Atualize a pilha com a nova MappingsKey eMappingsVersion:

   Usando o console: abra o CloudFormation console, selecione sua pilha, escolha Atualizar, selecione Usar modelo atual e MappingsKey atualize MappingsVersion os parâmetros e com os novos valores.

   Usando a 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

Importante

Você deve alterar o MappingsVersion parâmetro sempre que atualizar os mapeamentos. A versão determina o KeyValueStore nome, que CloudFormation aciona a substituição pelos KeyValueStore dados atualizados. Mantenha o nome do MappingsKey arquivo MappingsVersion em sincronia (por exemplo, ...-v2.json comMappingsVersion=v2) para maior clareza.

Para reverter para uma versão anterior, atualize a pilha apontando para o arquivo e a versão anteriores.

Usando o console: abra o CloudFormation console, selecione sua pilha, escolha Atualizar, selecione Usar modelo atual e, em seguida, defina MappingsKey e MappingsVersion volte aos valores anteriores (por exemplo,v1).

Usando a 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-v1.json \
    ParameterKey=MappingsVersion,ParameterValue=v1 \
  --region us-east-1

Essa abordagem com controle de versão oferece controle total para avançar ou reverter os mapeamentos do aplicativo conforme necessário, mantendo os arquivos do S3 como o registro definitivo de cada versão de configuração.

Configuração sem o Route 53 (configuração manual)

Se seu domínio for gerenciado por um provedor de DNS diferente do Route 53, você poderá configurar redirecionamentos de URL amigáveis manualmente no AWS Management Console. Essa abordagem não usa o Amazon S3 para mapeamentos — você gerencia pares de valores-chave diretamente no console. CloudFront

Para configurar um redirecionamento de URL amigável sem o Route 53

1. Solicite um certificado no ACM

   1. Abra o console do ACM em https://console.aws.amazon.com/acm/ na us-east-1 região.

   2. Escolha Solicitar certificado.

   3. Em Nome de domínio, insira *.your-domain.com (certificado curinga).

   4. Em Método de validação, escolha Validação de DNS.

   5. Escolha Solicitar.

   6. Na página de detalhes do certificado, observe o nome e o valor do registro CNAME em Validação de domínio. Crie esse registro CNAME no seu provedor de DNS para validar a propriedade do domínio.

   7. Aguarde até que o status do certificado mude para Emitido (normalmente 5 a 30 minutos após a criação do registro DNS).

2. Crie um CloudFront KeyValueStore

   1. Abra o CloudFront console em https://console.aws.amazon.com/cloudfront/.

   2. Selecione Funções no painel de navegação. Em seguida, escolha a KeyValueStores guia.

   3. Escolha Criar KeyValueStore.

   4. Insira um nome (por exemplo,opensearch-ui-friendly-url-app-mappings-store).

   5. Escolha Criar.

   6. Após a criação, escolha Editar para adicionar pares de valores-chave. Para cada aplicativo, adicione uma chave (o nome do subdomínio, comoprod) e um valor (a URL completa do aplicativo de OpenSearch interface do usuário).

3. Crie uma CloudFront função

   1. Abra o CloudFront console em https://console.aws.amazon.com/cloudfront/.

   2. Selecione Funções no painel de navegação.

   3. Na guia Funções, escolha Criar função.

   4. Insira um nome para a função (por exemplo,opensearch-ui-friendly-url-redirect-function).

   5. Em Runtime, escolha cloudfront-js-2.0.

   6. Substitua o código da função pelo seguinte:

      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>'
            }
          };
        }
      }

      YOUR_KVS_IDSubstitua pelo ID do KeyValueStore que você criou (visível na página de KeyValueStore detalhes).

   7. Nas KeyValueStore associações, associe as KeyValueStore que você criou.

   8. Escolha Salvar alterações e, em seguida, função Publicar.

4. Crie uma CloudFront distribuição

   1. No CloudFront console, escolha Criar distribuição.

   2. Para domínio Origin, insira qualquer domínio válido (por exemplo,example.com). A origem nunca é contatada porque a função retorna uma resposta antes de alcançá-la.

   3. Em Comportamento de cache padrão, para Política de protocolo do Viewer, escolha Redirecionar HTTP para HTTPS.

   4. Em Política de cache, escolha CachingDisabled.

   5. Em Associações de funções, para Solicitação do visualizador, selecione sua CloudFront função.

   6. Em Configurações, em Nomes de domínio alternativos (CNAMEs), insira*.your-domain.com.

   7. Em Certificado SSL personalizado, selecione o certificado que você criou no ACM.

   8. Escolha Create distribution (Criar distribuição).

   9. Anote o nome do domínio de distribuição (por exemplo,d1234abcdef8.cloudfront.net).

5. Configure o DNS em seu provedor

   No seu provedor de DNS, crie um registro CNAME que aponte *.your-domain.com para seu nome de domínio de CloudFront distribuição (por exemplo,d1234abcdef8.cloudfront.net).

   nota

   Alguns provedores de DNS não oferecem suporte a registros CNAME curinga. Nesse caso, crie registros CNAME individuais para cada subdomínio que você deseja usar (por exemplo,prod.your-domain.com,staging.your-domain.com).

Adicionar mapeamentos de aplicativos manualmente

Para adicionar novos mapeamentos de aplicativos após a configuração manual inicial:

1. Abra o CloudFront console em https://console.aws.amazon.com/cloudfront/.

2. Selecione Funções no painel de navegação. Em seguida, escolha a KeyValueStores guia.

3. Escolha seu KeyValueStore nome (por exemplo,opensearch-ui-friendly-url-app-mappings-store).

4. Escolha Editar.

5. Escolha Adicionar par. Insira o nome do subdomínio como chave e o URL completo do aplicativo de OpenSearch interface do usuário como valor.

6. Escolha Salvar alterações.

O novo URL amigável está disponível imediatamente após o salvamento.

Limpeza

Para remover a infraestrutura amigável de redirecionamento de URL, execute o seguinte comando:

aws cloudformation delete-stack \
  --stack-name opensearch-ui-friendly-url \
  --region us-east-1

Esse comando remove a CloudFront distribuição, a função KeyValueStore, o certificado ACM e o registro DNS. Isso não afeta seus aplicativos de OpenSearch interface do usuário.

Solução de problemas

O certificado ACM permanece em vigor Pending validation

Certifique-se de que o DNS do seu domínio esteja adequadamente delegado ao Route 53 (ou que você tenha criado o CNAME de validação no seu provedor de DNS). Use dig your-domain NS para verificar os servidores de nomes.

O navegador mostra um erro de certificado

Verifique se o certificado ACM cobre seu domínio como curinga ()*.your-domain.com. O certificado deve estar na us-east-1 Região.

404 Aplicativo não encontrado

O subdomínio que você está tentando acessar não tem um mapeamento no KeyValueStore. Verifique se a chave existe em seu arquivo de mapeamento e confirme se você atualizou a pilha (ou adicionou o par manualmente) após a última alteração.

CloudFront a distribuição mostra Deploying o status por mais de 15 minutos

CloudFront as distribuições podem levar até 15 minutos para serem implantadas globalmente. Se a implantação demorar mais, verifique os detalhes do erro no CloudFront console.

SourceArn é um erro inacessível durante a criação da pilha

Certifique-se de que a política de bucket do S3 conceda cloudfront.amazonaws.com permissão para ler o arquivo de mapeamento. Verifique também se a função do IAM que está implantando a pilha tem s3:GetObjects3:HeadObject, e s3:GetBucketLocation permissões no bucket.