Como migrar para o plug-in do Gradle baseado na CLI gcloud

Se você já usou o plug-in baseado no SDK do App Engine para Java (com.google.appengine.appengine-gradle) e quiser passar para a nova Google Cloud CLI, migre para o plug-in (com.google.cloud.tools.appengine-gradle) baseado em CLI ().

Benefícios do plug-in baseado na CLI gcloud

O upgrade para o novo plug-in oferece os seguintes benefícios:

  • Usa as mesmas credenciais de autenticação que todos os outros comandos baseados na CLI gcloud, que são provenientes do fluxo padrão gcloud auth login. .

  • É compatível com o ambiente flexível do App Engine.

  • Atualiza o servidor de desenvolvimento local automaticamente como parte do fluxo padrão de atualização da CLI gcloud.

  • É compatível com a implantação das configurações de serviço do App Engine (cron, filas, DoS, expedição), independentemente do serviço.

Diferenças significativas

Antes de migrar, esteja ciente destas diferenças significativas:

Dependência da CLI gcloud
O plug-in antigo pode ser executado sem dependências de ambiente local específicas, além do Java, mas o novo plug-in exige a instalação da CLI gcloud.
Sem geração de documentos de descoberta do Endpoints
O novo plug-in não gera documentos de descoberta do Endpoints. Esse recurso está disponível em um plug-in diferente. A execução do back-end do Endpoints não exige mais a geração desse arquivo em etapas de criação, já que agora ele é gerado pelo servidor no ambiente de execução. Use o novo plug-in somente se você precisar gerar bibliotecas de cliente para iOS ou Android, por exemplo. Saiba mais sobre os novos plug-ins no guia Como migrar para o Endpoints Frameworks para App Engine.
O formato de arquivo EAR não é mais aceito
O novo plug-in não é mais compatível com o formato de arquivo EAR para executar e implantar vários serviços ao mesmo tempo.
Novo comando de implantação
O plug-in antigo chama o comando appcfg para implantar aplicativos, enquanto o novo plug-in faz a implantação usando a nova CLI do gcloud.
O aprimoramento de JPA/JDO do DataNucleus precisa ser configurado manualmente
Se seu projeto usa o aprimoramento JPA/JDO do Datanucleus de gradle-appengine-plugin, é necessário configurar manualmente o aprimoramento do Datanucleus depois de mudar para o plug-in baseado na CLI gcloud. Veja um exemplo do Stackoverflow (em inglês).
O Android Studio não é compatível
É possível fazer com que seu projeto do Android Studio use o novo plug-in, mas o servidor de desenvolvimento do App Engine do Android Studio e o suporte à implantação não funcionarão com o novo plug-in. Para executar e implantar o aplicativo, é preciso invocar o Gradle diretamente.

O uso de arquivos de configuração XML é aceito, mas não YAML.

Como migrar para o novo plug-in

  1. Remova a configuração e as importações antigas de gradle-appengine-plugin do seu arquivo build.gradle.

  2. Adicione o novo plug-in ao classpath da seção buildscript do arquivo build.gradle:

    buildscript {
        repositories {
            mavenCentral()
        }
    
        dependencies {
            classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1'
        }
    }
    
  3. Na raiz do serviço, execute o seguinte comando para verificar se é possível executar o aplicativo localmente:

    gradle appengineRun
    
  4. Na seção buildscript do arquivo build.gradle, configure a implantação especificando o código e a versão do projeto:

    appengine {
        deploy {
            version = 'v1'
            project = "your GCP project ID"
        }
    }
    

    As novas ferramentas ignoram os elementos do aplicativo e da versão no arquivo appengine-web.xml.

  5. Na raiz do serviço, execute o seguinte comando para verificar se é possível implantar o aplicativo:

    gradle appengineDeploy
    

Como migrar configurações multisserviço baseadas em EAR

O novo plug-in não é compatível com empacotamento EAR. Em vez disso, ele aceita a execução de vários serviços localmente sem qualquer etapa especial de empacotamento.

Para migrar o projeto do Gradle baseado em EAR:

  1. Escolha um serviço principal que será responsável pela execução do resto dos serviços. Selecione um serviço padrão, que pode ser qualquer um dos serviços executados em conjunto.

  2. Na configuração appengine, modifique a entrada run.services para incluir todos os serviços que precisam ser executados pelo servidor de desenvolvimento local.

    Um exemplo de estrutura de projeto:

    ../{projectRoot}/
      build.gradle
      settings.gradle (includes default-service & secondary-service)
           {your-default-service}/build.gradle {includes appengine-gradle-plugin}
              .
           {your-default-service}/src/main/webapp/WEB-INF/appengine-web.xml
           {your-secondary-service}build.gradle {includes appengine-gradle-plugin}
              .
           {your-secondary-service}/src/main/webapp/WEB-INF/appengine-web.xml
    

    Um exemplo de buildscript build.gradle:

    appengine {
        run {
            // configure the app to point to the right service directories
            services = [
                    projectAsService(project),
                    projectAsService(":another-module")
            ]
        }
    }
    
    // helper method to obtain correct directory and set up dependencies
    def getExplodedAppDir(Project serverProject) {
        // if not 'this' module, then do some setup.
        if (serverProject != project) {
            // make sure we evaluate other modules first so we get the right value
            evaluationDependsOn(serverProject.path)
            // make sure we build "run" depends on the other modules exploding wars
            project.tasks.appengineRun.dependsOn serverProject.tasks.explodeWar
        }
        return serverProject.tasks.explodeWar.explodedAppDirectory
    }
    

Comandos baseados no SDK do App Engine vs. comandos do Gradle baseados na CLI gcloud

Na tabela a seguir, mostraremos as diferentes maneiras de invocar o plug-in do Gradle, seja baseado na CLI gcloud.

Ação Baseado do SDK do App Engine Baseado na CLI do gcloud
Executar o aplicativo localmente appengine:devserver appengineRun
Implantar um novo aplicativo, versão ou serviço. appengine:update appengineDeploy
Definir a versão padrão do aplicativo. appengine:set_default_version gcloud app services set-traffic ou gcloud app versions migrate
Atualizar os cron jobs do aplicativo. appengine:update_cron appengineDeployCron
Atualizar a configuração de expedição do aplicativo. appengine:update_dispatch appengineDeployDispatch
Atualizar a configuração da proteção contra DoS do aplicativo. appengine:update_dos appengineDeployDos
Atualizar as definições da fila de tarefas do aplicativo. appengine:update_queues appengineDeployQueue
Atualizar os índices do armazenamento de dados. appengine:update_indexes appengineDeployIndex
Excluir os índices não utilizados do aplicativo. appengine:vacuum_indexes limpeza de índices do armazenamento de dados da gcloud
Inicia a versão de módulo especificada. appengine:start_module_version gcloud app versions start
Parar a versão de módulo especificada. appengine:stop_module_version gcloud app versions stop
Reverter uma atualização em andamento. appengine:rollback gcloud app versions start, gcloud app versions stop

A seguir

  • Agora que você migrou para o novo plug-in com sucesso, é possível testar e implantar o aplicativo.