{"id":21334302,"url":"https://github.com/uselagoon/advanced-task-toolbox","last_synced_at":"2025-03-16T01:25:15.053Z","repository":{"id":51821503,"uuid":"496366697","full_name":"uselagoon/advanced-task-toolbox","owner":"uselagoon","description":"This repo contains a framework for automating tasks on Lagoon","archived":false,"fork":false,"pushed_at":"2024-07-04T01:23:19.000Z","size":129,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-22T14:22:37.847Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uselagoon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-05-25T19:38:57.000Z","updated_at":"2024-07-04T01:23:19.000Z","dependencies_parsed_at":"2022-08-13T01:10:43.707Z","dependency_job_id":"872a5389-a99c-4b7c-bd20-4dbafa57ec6f","html_url":"https://github.com/uselagoon/advanced-task-toolbox","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uselagoon%2Fadvanced-task-toolbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uselagoon%2Fadvanced-task-toolbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uselagoon%2Fadvanced-task-toolbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uselagoon%2Fadvanced-task-toolbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uselagoon","download_url":"https://codeload.github.com/uselagoon/advanced-task-toolbox/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243812043,"owners_count":20351821,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-21T23:19:46.456Z","updated_at":"2025-03-16T01:25:15.018Z","avatar_url":"https://github.com/uselagoon.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lagoon Advanced Task Toolbox\n\nThis application provides a generic toolbox that is meant to abstract generic in-namespace administrative functions,\ntypically invoked from inside a Lagoon custom (image) task.\n\nScripts are written using an ansible-like yaml format. In general the structure of the scripts are as follows\n\n```\nprerequisites:\n    - \u003cscript steps appear here\u003e\nsteps:\n    - \u003cscript steps appear here\u003e\nrollback:\n    - \u003csteps to rollback appear here\u003e\n```\n\nThere are three top level sequences, `prerequisites`, `steps` and `rollback`. The entries in `steps` specify the actual\nsteps that will be run when the application is invoked, while the (optional) `rollback` sequence defines steps that are\nrun if any of the steps in `steps` sequence fail. Any steps that can appear in the `steps` sequence can appear\nin `rollback`. The `prerequisites` array is optional and will play any steps that can appear in `steps` except that if\nany of these fail, the task will exit and the rollback steps *will not be run*.\n`prerequisites` is a very good place to run any *assertions* (below) to ensure that the task can and should be run on\nthe target environment.\n\nThe kinds of steps supported are described below.\n\n---\n\n## Using the Advanced Task Toolbox\n\nThe Advanced Task Toolbox is (currently) a [Robo](https://robo.li/) application, and requires PHP 8.1. The Dockerfile in\nthis repository is based on the `uselagoon/php-8.1-cli` image.\n\nBy _default_ if you don't explicitly invoke the application with a particular script by using the `--migrateYaml`\noption, the task toolbox will look for a task argument (in the task's JSON_PAYLOAD) called `migrateYaml`. If neither are\nprovided, the task will not run.\n\nThere are two potential ways of using this application.\n\nFirst:\n\n1. Create a new dockerfile with `FROM amazeeio/advanced-task-toolbox:latest`\n2. `COPY` any scripts you need into `/app/scripts`\n3. Publish your new image and use it in a custom advanced task.\n\nSecond:\n\n1. Fork the repo\n2. Add your scripts to ./scripts/\n3. Publish an image to use in a custom task\n\n**Note** you will need to create a custom task of `type: IMAGE`, which is currently only available to platform\nowners/admins. Advanced tasks are potentially very destructive and should be used _very carefully_.\n\n***\n\n## Assertions\n\nAssertions are simple boolean checks that will throw an exception if they are not met. With the `assertTrue`\nand `assertFalse` fields you are able to specify the conditions under which an assertion will pass. Currently, the\ntoolbox supports the following assertions.\n\n### currentopenshift\n\nThis assertion will allow you to test whether the target environment is _currently_ on a particular deploytarget.\n\nFor example, if we wanted to assert that a particular environment's deploytarget should be 3, we could use\n\n```\n  - name: Current openshift should be 3\n    assertTrue: currentopenshift\n    target: 3\n```\n\nIf we wanted to assert that it _shouldn't_ currently be 3, we could do the following.\n\n```\n  - name: Current openshift should NOT be 3\n    assertFalse: currentopenshift\n    target: 3\n```\n\nTypically you would run this as part of the `prerequisites` step to ensure you aren't going to apply a set of\ntransformations in the wrong namespace.\n\n### environmenttype\n\nThis allows you to assert that an environment is either \"production\" or \"development\"\n\n```\n- name: Current environment should be development, not production\n  assertTrue: environmenttype\n  environmentType: development\n```\n\n### fileexists\n\nWill assert that a particular file exists on disk before running the migration\n\n```\n  - name: Test file exist\n    assertTrue: fileexists\n    filename: /tmp/.testfile\n```\n\n## Retrying on failure\n\nAll steps can take the following optional fields to set retry parameters\n\n```\n    retry: 3 #optional, default 0 - the number of times to retry step if failed\n    retryDelaySeconds: 5 #optional, default 10 - the delay between retry attempts\n```\n\n## Step types\n\nCurrently, the toolbox supports the following functions.\n\n#### Text Substitutions with environment variables\n\nSome of the steps below support the notion of text substitution - that is, you're able to use string templates of the \nform `{{ substitutionname }}` and before the step is run, it will replace the substitution with the appropriate text.\n\nThis system also allows for substitutions from environment variables. For instance, if you have an environment variable of the name\n`SYSTEM_NAME`, you can use that in the step substitutions by referencing it as `{{ SYSTEM_NAME }}`\n\nWe use [twig](https://twig.symfony.com/) for formatting, which makes it simple to add default values, for instance, if `SYSTEM_NAME` is only available conditionally, we can do something like `{{ SYSTEM_NAME ?? 'default val' }}`\n\n### Exec\n\nThe exec step allows you to run a command from inside the current advanced task's container, or within another pod.\n\nTo run a command in the advanced task's container, you can do the following\n\n```\nsteps:\n  - name: run local echo\n    type: exec\n    local: true\n    command: echo \"This is running in the advanced task's container\"\n```\n\nTo run a command in another pod, you can run the following, specifying `deployment` with the deployment you're\ntargeting.\n\n```\nsteps:\n  - name: run echo on the cli pod\n    type: exec\n    deployment: cli\n    command: echo \"Running in the cli pod in namespace %namespace%\"\n```\n\n### Text substitutions\n\nThe `exec` step allows you to do textual substitutions in the `command`.\n\nIt will do the following substitutions\n\n* '{{ project }}' for current project name\n* '{{ environment }}' for the current environment\n* '{{ namespace }}' for the current namespace\n\n### scale\n\nWhen running a command in another pod in the namespace, you will need to ensure that the pod is actually available. If\nit has been auto-idled, for instance, you will need to scale up the deployment before running your command. The `scale`\nstep will attempt to scale up a deployment if there are currently no running pods.\n\n```\nsteps:\n  - name: Scale up cli deployment\n    type: scale\n    deployment: cli\n```\n\n### deploy\n\nThe deploy step will attempt to deploy the current environment.\n\n```\n  - name: Deploy\n    type: deploy\n    [skipDeploymentWait: true]\n    [registerBuildIdAs: *variablename*]\n    [passIfTextExistsInLogs: \"STEP Cronjob Cleanup: Completed\"]\n```\n\nThe key/value pair `passIfTextExistsInLogs` is optional. Sometimes, despite a deployment failing, it may have deployed\nfar enough to be considered \"deployed\". This option allows you to specify some text that may appear in the logs that, if\nthere, let's us consider a deployment as \"deployed\", despite failing.\n\nSometimes you don't need to wait for the outcome of the deployment before moving on to another task, in this case you\ncan use `skipDeploymentWait: true`, this will simply move onto the next task after the deployment has begun.\n\nIf you would like to use the build id in subsequent steps (for example in a text substitution in an `exec` or as input\nfor a `waitfordeploy`) you can register a variable using `registerBuildIdAs`, which will then be available to subsequent\nsteps.\n\n### waitfordeploy\n\n```\nsteps:\n  - name: Deploy\n    type: deploy\n    skipDeploymentWait: true\n    registerBuildIdAs: thebuildid\n  - name: echo build id\n    type: exec\n    local: true\n    command: echo \"%thebuildid%\"\n  - name: wait for deployment\n    type: Waitfordeploy\n    buildId: thebuildid\n    [passIfTextExistsInLogs: \"STEP Cronjob Cleanup: Completed\"]\n```\n\n`waitfordeploy` will typically be used in combination with skipping a deploy and registering an id. \n\n### copyto\n\nIf there is a file that is delivered along with the advanced task, for instance, a particular version of the lagoon-sync\ntool, this step type can be used to copy that file to the target deployment/pod.\n\nThis _requires_ the file to exist on the advanced task image.\n\n```\n  - name: copy lagoon sync to cli pod\n    type: copyto\n    deployment: cli\n    source: /usr/bin/lagoon-sync\n    destination: /tmp/lagoon-sync-from-advanced-task\n```\n\nIn the example above, the file `/usr/bin/lagoon-sync` on the advanced task image, is copied to the cli pod\nat `/tmp/lagoon-sync-from-advanced-task`\n\n### setdeploytarget (dangerous)\n\nThis will change the deploy target for the current namespace. This is potentially an extremely destructive operation and\nshould be done with caution. Once the change is effected, the environment will need to be redeployed in order for the\nshift to the new deploy target.  \nIn order to do this, you need the id of the new openshift/deploy target.\n\n```\n  - name: Change deploy target\n    type: setdeploytarget\n    target: \u003cnew deploy target id\u003e\n```\n\n### setservicename (experimental/dangerous)\n\nThis allows you to set the service name for the currently running advanced task.\n\n```\n  - name: Set service name for current task\n    type: setservicename\n    servicename: advanced-task-service\n```\n\nThis can be used if you need to `ssh` into the currently running advanced task.\n\n### waitforfile\n\nWill pause the task process until the given file exists on disk.\n\n```\n  - name: Wait for config file before continuing\n    type: waitforfile\n    filename: /etc/someservice/someconfigfile\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuselagoon%2Fadvanced-task-toolbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuselagoon%2Fadvanced-task-toolbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuselagoon%2Fadvanced-task-toolbox/lists"}