Manifesto de Carol App
Esta seção tem o objetivo de apresentar o arquivo de manifesto e compartilhar alguns projetos de amostra disponíveis em repositórios públicos.
O arquivo de manifesto é criado automaticamente ao criar um novo aplicativo Carol (Online ou Batch).
Arquivo de exemplo
A seguir um exemplo do arquivo de manifesto:
JSON
{
"batch": {
"processes": [{
"algorithmDescription": {
"en-US": "Batch task Description",
"pt-BR": "Descrição do Tarefa Batch"
},
"algorithmName": "batch_carolapp_algorithm",
"algorithmTitle": {
"en-US": "Batch task Description",
"pt-BR": "Descrição do Tarefa Batch"
},
"dataModels": [],
"instanceProperties": {
"properties": {
"dockerName": "batch_carolapp-batch_carolapp_algorithm",
"instanceType": "c1.nano",
"preemptible": false
}
},
"name": "batch_carolapp"
}]
},
"online": {
"processes": [{
"algorithmDescription": {
"en-US": "Online Description",
"pt-BR": "Descrição do Online app"
},
"algorithmName": "online_app",
"algorithmTitle": {
"en-US": "Online Description",
"pt-BR": "Descrição do Online app"
},
"instanceProperties": {
"profile": "",
"properties": {
"instanceType": "c1.micro",
"dockerImage": "online_app",
"autoscale": {
"enabled": true,
"minReplicas": 1,
"maxReplicas": 4
},
"healthcheck": {
"path": "/healthy"
},
"port": 8080,
"preemptible": true
}
},
"name": "online_carolapp"
}]
},
"docker": [{
"dockerName": "batch_carolapp-batch_carolapp_algorithm",
"dockerTag": "0.1.0",
"gitBranch": "app_review",
"gitPath": "/batch_carolapp",
"gitDockerfileName": "Dockerfile",
"gitRepoUrl": "https://github.com/totvslabs/carolapp-samples"
}]
}
Compreendendo o arquivo de manifesto
Esta seção explica as propriedades mais importantes no arquivo de manifesto.
| Parâmetro | Descrição |
|---|---|
| batch/online | O mesmo arquivo pode especificar a configuração para o aplicativo em lote e online Carol. Isso significa que o aplicativo Carol suporta os dois tipos de aplicativo Carol, incluindo o recurso da Web, sendo implantado como um recurso separado na Carol. |
| algorithmDescription/algorithmTitle | Ambas as propriedades permitem especificar informações que estarão disponíveis na tela para o usuário que opera o aplicativo Carol. Essas propriedades suportam internacionalização. |
| algorithmName | Esta propriedade especifica o nome do algoritmo responsável por inicializar a execução do Batch Carol App ou Online Carol App. |
| instanceProperties | Permitir a especificação de algumas propriedades personalizadas para o aplicativo Carol. Algumas propriedades predefinidas são descritas abaixo (docker, por exemplo). |
| dataModels | Especifique os modelos de dados que este processo está procurando por eventos (alteração, um novo registro ou registros excluídos) para ativar a próxima tarefa agendada. Se não tiver evento, a tarefa será criada na Carol apenas para deixar claro para o usuário que o cronograma está funcionando, mas nenhuma instância e nenhum processo serão executados. |
| instanceProperties.properties.dockerName | A propriedade dockerName refere-se à instância direita do docker abaixo. Especificando todas as configurações relacionadas ao docker, como tag , gitBranch , gitpath, instanceType, gitDockerfilename , gitRepoUrl. |
| instanceProperties.properties.gitRepoUrl | A propriedade gitRepoURL refere-se ao caminho do repositório onde a imagem docker e demais fontes do Carol App se encontram e é utilizada no processo de checkout. Lembre-se de apenas colocar a URL até o local raiz do repositório, evitando colocar algum caminho específico, o que implicará em erros ao realizar o clone do repositório. |
| instanceProperties.properties.gitPath | A propriedade gitpath refere-se ao caminho específico onde a imagem docker do Carol App se encontra. Lembre-se de apenas colocar o caminho absoluto, logo após a raiz do repositório e sem incluir o nome do arquivo. Deste modo o processo de validação irá correr sem erros. |
| instanceProperties.properties.gitDockerfileName | A propriedade gitDockerfilename refere-se apenas ao nome do arquivo docker. Esta propriedade é combinada com a propriedade gitpath durante o processo de validação da build. |
| instanceProperties.properties.instanceType | Este é o tipo de instância para executar o processo Carol App. |
| instanceProperties.preemptible | O valor true especifica que a instância pode morrer subitamente e false significa que a instância é mais robusta (e cara) e não morre subitamente. Normalmente, os aplicativos em lote são aceitáveis com preemptivo como true, mas recomendamos fortemente que os aplicativos on-line usem como false preemptivo. O valor padrão é true. |
| name | Este é o identificador para os processos (online e batch) dentro do arquivo de manifesto. |
| docker | Esta seção descreve todas os dockers usados pelo arquivo de manifesto. O link acontece através do dockerName tag. Essa propriedade especifica a seguinte configuração relacionada a esta imagem docker, como tag, gitBranch, gitpath, gitRepoUrl. Essa configuração foi adicionada recentemente, após a implantação 3.7, mas os arquivos antigos do manifesto sem essa propriedade ainda são suportados. |
| instanceProperties.properties.autoscale | Essa configuração está disponível apenas para aplicativos online, permitindo ativar o dimensionamento automático (com base no uso da CPU), bem como as réplicas mínima e máxima que um aplicativo online deve ter. |
| instanceProperties.properties.autoscale.enabled | Se o aplicativo deve ser escalado automaticamente ou não. Se ativado, ele irá escalar o aplicativo se o uso médio da CPU estiver acima de false . |
| instanceProperties.properties.autoscale.minReplicas | Réplicas mínimas que um aplicativo deve ter. O padrão é 1 . |
| instanceProperties.properties.autoscale.maxReplicas | Máximo de réplicas que um aplicativo deve ter. Deve ser maior que minReplicas e no máximo 5. |
| instanceProperties.properties.healthcheck.path | A configuração healthcheck está disponível apenas para aplicativos online, permitindo definir um caminho personalizado para a verificação de integridade do aplicativo. Esta configuração neste cenário torna-se Obrigatória, pois a falta dela incorrerá em instabilidades na inicialização do aplicativo online. O padrão é /. |
| instanceProperties.properties.port | Personalize a porta na qual o aplicativo online escuta. O padrão é 5000. |
| instanceProperties.properties.command | O comando a ser executado pelo contêiner. Equivalente à propriedade Docker ENTRYPOINT. |
| instanceProperties.properties.args | Os argumentos passados para o comando que o contêiner executará. |
| instanceProperties.properties.deadline | Tempo máximo que um lote pode ser executado. Deve ser informado em segundos, minutos ou horas. Por exemplo: 40s, 15m, 1h . O limite rígido é de 24 horas. |
| instanceProperties.properties.environments | Contempla as variáveis de ambiente utilizadas na interface de porta de entrada do servidor web (WSGI) que definem sua capacidade de atendimento aos processos iniciados pelo aplicativo. Para Python é utilizada a implementação Gunicorn e as variáveis utilizadas tanto no seu arquivo de configuração quanto no manifesto são: workers, threads e timeout. |
Exemplo de configuração da propriedade environments
Cabe ressaltar que o seu correto dimensionamento é de responsabilidade do cliente e vai depender da: quantidade de core na CPU da instância, do Carol App e da stack de tecnologia utilizada. Um mal dimensionamento poderá ocasionar problemas de sobrecarga por concorrência (requisições simultâneas) levando o aplicativo a reinicializações frequentes.
Os valores utilizados no exemplo abaixo são apenas ilustrativos e sua alteração fica a critério do cliente.
gunicorn.conf.py
-workers = 1
-threads = 16
-timeout = 240
bind = ":5000"
O parâmetro bind vinculará o aplicativo no host local nas interfaces ipv6 e ipv4.
Dúvidas sobre este parâmetro? → Veja mais informações em Server Socket.
manifest file
"dockerImage": "carolappprd/carolappapiprd:1.0.0",
"instanceType": "c1.large",
"preemptible": false
},
"environments": {
"GUNICORN_CMD_ARGS": "--workers 8 --threads 16 --timeout 240"
}
}
}
Dúvidas sobre a configuração das variáveis? → Veja mais informações em Worker Processes.
Tipo de Instância
A documentação a seguir compartilha todos os tipos de instância possíveis.
Especificação de uma imagem externa do Docker
Você pode especificar um nome de imagem docker externo (URL) substituindo as propriedades dockerName em instanceProperties/properties por dockerImage.
Um exemplo completo dessa configuração está disponível aqui: https://github.com/totvslabs/carolapp-samples/blob/master/online-nodejs-carolapp/ai-script/manifest.json
Possíveis incidentes
Se algo der errado, você verá a seguinte tela:
O problema mais comum é especificar a versão latest para pyCarol. É obrigatório especificar uma versão, pois hoje (23/02/2020) a versão mais recente e estável é a 2.30.0.