Migração para API v4

Visão geral da migração

Azion está lançando a API v4 nos próximos meses para aprimorar o desempenho, a flexibilidade e a gestão de recursos da plataforma. Esta atualização vai além de uma simples mudança de API: ela introduz um novo conceito central, Workloads, além de novos produtos como Connectors e Custom Pages, e traz melhorias significativas tanto para a API quanto para o Console da Azion.

A API v4 apresenta uma nova arquitetura assíncrona e orientada a eventos, projetada para maior desempenho e resiliência. O novo modelo de recurso Workload centraliza a configuração, facilitando o gerenciamento, reutilização e escalabilidade das suas aplicações. O Connectors permite integrações de backend mais flexíveis e seguras.

A API v4 da Azion já está disponível em Preview para novas contas do plano Developer e será liberada em ondas para Disponibilidade Geral (GA) de acordo com o seu plano de serviço.

Pontos-chave sobre a migração:

• A migração afeta tanto a plataforma (com a introdução de Workloads, Connectors e Custom Pages) quanto os endpoints da API.
• Algumas configurações foram movidas para novos locais para melhorar a reutilização e a clareza.
• Novas contas developer usarão a API v4 por padrão. Contas existentes serão migradas em ondas.
• Durante a transição, você pode ver documentações com banners permitindo alternar entre as versões v3 e v4 de um recurso.
• Após a migração da sua conta, não será mais possível utilizar os endpoints da API v3 ou criar novos Domains, Origins ou Error Responses. Você deverá utilizar os novos recursos equivalentes.

A API v4 representa um avanço tecnológico, fornecendo a base para futuras funcionalidades e maior eficiência operacional em toda a Azion Web Platform.

Migração da API

Todos os endpoints da API serão migrados para a v4 em ondas. Para visualizar os endpoints e parâmetros disponíveis, consulte a referência da API v4.

A API v3 está agora obsoleta e não receberá mais atualizações. Ela será descontinuada em uma data futura. Após essa data, todas as operações deverão ser realizadas exclusivamente utilizando a API v4.

Ações necessárias

Automatizações, scripts e pipelines de CI/CD conectados à Azion devem ser atualizados para utilizar a API v4 até o prazo especificado.

Novas funcionalidades

• Autenticação JWT.
• Histórico de atividades via GraphQL para auditoria completa.
• Nova arquitetura orientada a eventos.

Benefícios da migração

• Desempenho aprimorado
• Maior flexibilidade
• Acesso a updates futuros.
• Parâmetros de consulta: Agora você pode usar parâmetros de consulta para personalizar solicitações de API. As opções suportadas incluem ordenar resultados por um campo específico e filtrar resultados por um termo de pesquisa ou por valor de campo. Isso permite que você recupere e organize dados de acordo com seus requisitos.

Mudanças nas Applications

A funcionalidade das Applications permanece inalterada. No entanto, algumas opções de configuração que antes eram gerenciadas dentro das Applications foram movidas para outros componentes como parte da migração.

Workloads

A Azion adotou o conceito de Workload para centralizar a lógica da aplicação, separando regras de negócio da infraestrutura. Isso permite reutilização e aplicação consistente de políticas entre ambientes, seguindo um modelo inspirado no Kubernetes.

Workloads substituem os Azion Domains. Todas as configurações anteriormente gerenciadas em Azion Domains agora estão organizadas sob Workloads.

Mudanças operacionais e impacto para o usuário

As seguintes configurações foram movidas de Azion Domains para Workloads.

Delivery Settings que antes eram configuradas dentro de uma Applications agora podem ser encontradas em Workloads em Protocol Settings:

• Protocol Settings
• Delivery Ports
• Minimum TLS version
• TLS Ciphers

Mudanças comportamentais notáveis

• CNAME Access Only
  • Comportamento anterior: Quando ativado, a aplicação só podia ser acessada via CNAME (por exemplo, app.example.com).
  • Novo comportamento: Substituído por “Workload Domain Allow Access”, permitindo acesso pela URL gerada automaticamente do workload (por exemplo, xxxxxxxx.map.azionedge.net).

Uso da API

Cada Workload está implicitamente associado a um Deployment. O Deployment define a relação entre o Workload e a Applications (obrigatório), além de componentes opcionais como Firewall e Custom Pages.

Ao criar um Workload via API, você também deve criar um Workload Deployment para vincular o Workload a uma Applications. Essa associação garante que o Workload esteja corretamente vinculado à Applications desejada.

Ao utilizar o Console, essa associação é criada automaticamente ao selecionar Deployment Settings.

Exemplos de requisições

Criando um Workload:

curl --request POST --url https://api.azion.com/v4/workspace/workloads --header 'Accept: application/json' --header 'Authorization: Token [TOKEN VALUE]' --header 'Content-Type: application/json' -- '{
"name": "Example Workload",
"active": true,
"infrastructure": 1,
"protocols": {
  "http": {
    "versions": [
      "http1",
      "http2"
    ]
  }
},
"workload_domain_allow_access": true
}'

Criando um Workload Deployment:

curl --request POST --url https://api.azion.com/v4/workspace/workloads/<workload_id>/deployments --header 'Accept: application/json' --header 'Authorization: Token [TOKEN VALUE]' --header 'Content-Type: application/json' -- '{
"name": "Workload Deployment Example",
"current": true,
"active": true,
"strategy": {
  "type": "default",
  "attributes": {
    "edge_application": <edge_application_id>
  }
}
}'

O que acontece com meus Domains existentes?

Os Domains serão automaticamente convertidos em Workloads em fases, garantindo compatibilidade com as configurações originais. A migração ocorrerá em ondas.

Após a migração da sua conta, não será mais possível criar novos Domains.

Ação necessária

Se você possui automações que atualmente utilizam os endpoints da API de Domains, é necessário atualizá-las para utilizar os endpoints de Workloads da v4.

Novas funcionalidades

• Custom Pages: Substitui e expande o antigo recurso de Error Responses. Mais detalhes são fornecidos abaixo.
• Azion Custom Domain: Permite configurar um domínio personalizado da Azion para sua aplicação no formato example.azion.app.

Benefícios da migração

• Organização aprimorada: Agrupe logicamente todos os recursos relacionados a uma aplicação ou serviço em uma única unidade (Workload), tornando o gerenciamento, visualização e navegação mais eficientes. Essa estrutura cria relações claras entre os componentes.
• Escalabilidade e flexibilidade: Simplifica o deploy, atualizações e escalabilidade de aplicações complexas ao permitir que todos os componentes necessários sejam gerenciados como parte de um Workload.
• Gestão simplificada: Centraliza a configuração e o controle de diferentes elementos da aplicação, reduzindo a complexidade operacional.
• Base para novas capacidades: Essencial para recursos futuros, como versionamento de configuração e conexões de serviço mais intuitivas, por exemplo, vincular um domínio diretamente ao Object Storage sem depender de uma Applications.

Connectors

O Connectors centraliza as configurações de conexão com backends, permitindo reutilizá-las em múltiplas aplicações e fornecendo controle granular sobre desempenho, segurança e roteamento por meio de uma interface unificada para conectar Applications a uma origem (seu backend), incorporando nativamente recursos como balanceamento de carga, autenticação HMAC e Origin Shield.

O Connectors substitui as configurações de Origin das Applications. Todas as configurações anteriormente gerenciadas na aba Origins das Applications agora estão organizadas sob o Connectors.

Mudanças operacionais e impacto para o usuário

Todas as configurações anteriormente gerenciadas na aba Origins das Applications agora estão organizadas sob o Connectors.

Mudanças comportamentais notáveis

• Connector Type

  • Comportamento anterior: As opções incluíam Single Origin e Load Balancer. Isso definia se era possível configurar uma ou múltiplas origens.
  • Novo comportamento: Os tipos Single Origin e Load Balancer foram unificados no tipo HTTP. Ao usar múltiplas origens, é necessário habilitar o Load Balancer Module para adicionar mais origens.

• HMAC Authentication

  • Comportamento anterior: Disponível ao configurar uma Origin.
  • Novo comportamento: Agora é necessário habilitar o Origin Shield Module ao configurar um connector do tipo HTTP.

• Timeouts

  • Comportamento anterior: Connection Timeout e Between Bytes Timeout tinham valores fixos.
  • Novo comportamento: Agora é possível configurar os valores de Connection Timeout e Read/Write Timeout na seção de Load Balancer Configuration do connectors.

Uso da API

Você pode gerenciar Connectors e suas configurações pela API utilizando os endpoints v4 disponíveis. Consulte a referência da API para detalhes sobre operações e parâmetros suportados.

Exemplos de requisições

Criando um connector com o tipo Object Storage:

curl --request POST --url https://api.azion.com/v4/edge_connector/connectors --header 'Accept: application/json' --header 'Authorization: Token [TOKEN VALUE]' --header 'Content-Type: application/json' -- '{
"name": "object storage connector",
"active": true,
"type": "edge_storage",
"attributes": {
  "bucket": "app-origin",
  "prefix": "/"
}
}'

Criando um connector com o tipo HTTP:

curl --request POST --url https://api.azion.com/v4/edge_connector/connectors --header 'Accept: application/json' --header 'Authorization: Token [TOKEN VALUE]' --header 'Content-Type: application/json' -- '{
  "name": "example.com",
  "active": true,
  "type": "http",
  "attributes": {
    "addresses": [
      {
        "active": true,
        "address": "example.com",
        "http_port": 80,
        "https_port": 443,
        "modules": null
      }
    ],
    "connection_options": {
      "dns_resolution": "preserve",
      "transport_policy": "preserve",
      "http_version_policy": "http1_1",
      "host": "example.com",
      "path_prefix": "/",
      "following_redirect": true,
      "real_ip_header": "X-Real-IP",
      "real_port_header": "X-Real-PORT"
    },
    "modules": {
      "load_balancer": {
        "enabled": false,
        "config": null
      },
      "origin_shield": {
        "enabled": false,
        "config": null
      }
    }
  }
}'

O que acontece com meus Origins existentes?

As Origins existentes serão migradas de acordo com um cronograma, que será comunicado para cada caso. A migração ocorrerá em fases.

Ação necessária

Se você possui automações que atualmente utilizam os endpoints da API de Applications - Origins, é necessário atualizá-las para utilizar os endpoints da v4.

Novas funcionalidades

• Reutilização de configuração: O mesmo Connectors pode ser conectado a múltiplas Applications.
• Timeouts configuráveis: Os valores de Connection Timeout e Read/Write Timeout podem ser configurados na seção de Load Balancer Configuration do Connectors.

Benefícios da migração

• Gestão simplificada de backend: O Connectors centraliza todas as definições de conexão de backend, reduzindo a complexidade de configuração. Múltiplas Applications podem usar um único Connectors, facilitando a manutenção e garantindo consistência de configuração.
• Arquitetura pronta para o futuro: O Connectors fornece a base para novos recursos e otimizações da Azion Web Platform, garantindo que suas Applications estejam prontas para aproveitar novas capacidades assim que estiverem disponíveis.

Custom Pages

O Custom Pages é um recurso da Azion que permite personalizar páginas de erro para os usuários com base no código de status recebido de um Connectors ao buscar o conteúdo da sua origem.

O Custom Pages substitui as configurações de Error Responses das Applications. Todas as configurações anteriormente gerenciadas na aba Error Responses das Applications agora estão organizadas sob Custom Pages.

Mudanças operacionais e impacto para o usuário

Todas as configurações anteriormente gerenciadas na aba Error Responses das Applications agora estão organizadas sob Custom Pages.

Mudanças comportamentais notáveis

• Relacionamento

  • Comportamento anterior: As páginas de erro faziam parte de uma Applications.
  • Novo comportamento: Custom Pages são recursos separados e são vinculados a um Workload.

• Connectors por código de página

  • Comportamento anterior: Todas as respostas de erro precisavam ter a mesma Origin.
  • Novo comportamento: Agora é possível atribuir um Connectors específico para cada código de página de erro em Custom Pages. Isso permite personalizar a resposta para cada código de erro individualmente.

Uso da API

Você pode gerenciar Custom Pages e suas configurações pela API utilizando os endpoints v4 disponíveis. Consulte a referência da API para detalhes sobre operações e parâmetros suportados.

Para utilizar uma Custom Page, é necessário vinculá-la a um Workload usando o endpoint de Workload Deployment. Ao utilizar o Console, essa associação é criada na configuração de deployment do Workload.

Exemplos de requisições

Criando uma Custom Page:

curl --request POST --url https://api.azion.com/v4/workspace/custom_pages --header 'Accept: application/json' --header 'Authorization: Token [TOKEN VALUE]' --header 'Content-Type: application/json' -- '{
"name": "401 error page",
"active": true,
"pages": [
  {
    "code": "401",
    "page": {
      "type": "page_connector",
      "attributes": {
        "connector": <edge_connector_id>,
        "ttl": 300,
        "uri": "/path/error_page.html",
        "custom_status_code": 100
      }
    }
  }
]
}'

Vinculando uma Custom Page a um Workload Deployment:

curl --request POST --url https://api.azion.com/v4/workspace/workloads/<workload_id>/deployments --header 'Accept: application/json' --header 'Authorization: Token [TOKEN VALUE]' --header 'Content-Type: application/json' -- '{
"name": "Workload Deployment Example",
"current": true,
"active": true,
"strategy": {
  "type": "default",
  "attributes": {
    "edge_application": <edge_application_id>,
    "custom_page": <custom_page_id>
  }
}
}'

O que acontece com meus Error Responses existentes?

Os Error Responses existentes serão automaticamente convertidos em Custom Pages em fases, mantendo a compatibilidade com as configurações originais. A migração ocorrerá em ondas.

Novas funcionalidades

• Detalhes da resposta: Personalize a resposta para cada código de status. Especifique o URI, código de status, TTL a ser retornado ao cliente.
• Atribuição de Connectors por código de status: Atribua um connector específico para cada código de página de erro em Custom Pages. Isso permite personalizar a resposta para cada código de erro individualmente.

Benefícios da migração

• Opções de configuração abrangentes:
  • Defina um código de status personalizado para cada página.
  • Configure o tempo de vida (TTL) da resposta.
  • Especifique o caminho para a página personalizada.
  • Vincule cada página personalizada a um ou mais connectors.
• Ativação e gerenciamento:
  • Ative ou desative qualquer Custom Page usando um controle de status.
  • Visualize e gerencie uma lista paginada de todos os códigos de status configurados pela interface do usuário.

Cronograma planejado de migração

O processo de migração ocorrerá nos próximos seis meses.

Recomendações

Aqui estão ações recomendadas para garantir uma migração tranquila:

• Acompanhe as comunicações da Azion: Mantenha-se informado sobre datas de migração, guias e quaisquer ferramentas fornecidas para a transição.
• Planeje sua migração: Avalie como suas configurações atuais se encaixarão na nova estrutura e planeje estrategicamente a migração dos seus recursos.
• Prepare sua equipe: Garanta que sua equipe compreenda o conceito de Workloads e seu impacto no desenvolvimento e deploy de aplicações na Azion Web Platform.
• Teste as novas funcionalidades: À medida que os novos recursos forem implementados, teste as novas capacidades para otimizar suas aplicações e serviços.

Perguntas e Respostas

Como posso testar as novas funcionalidades?

Novas contas Developer terão acesso aos recursos atualizados. Para avaliar essas funcionalidades, você pode criar uma conta pessoal que não esteja associada à conta da sua organização. Isso permite testar as novas funcionalidades de forma independente.

Preciso fazer alguma coisa?

A maioria dos usuários não precisará tomar nenhuma ação, pois o processo de migração é automático e preserva as configurações existentes. No entanto, se você utiliza automações personalizadas, scripts ou pipelines de CI/CD que interagem com os endpoints antigos da API, será necessário atualizá-los para utilizar os novos endpoints da v4. Revise suas integrações para garantir a compatibilidade após a migração.

O que devo fazer se precisar de assistência?

Você pode entrar em contato com nossa equipe de suporte ou perguntar diretamente ao Azion Copilot.