Artifact Rollout with Ansible

Ansible is APP's new tool in 2023 for rolling out applications and services. It is available on the acc9 cluster (asl75x) and replaces the old release script.

This Wiki page is a short summary of the absolute minimum you have to know to perform rollout for your application or service. For more in-depth knowledge, please look at the Ansible documentation or the README of acoapp-ansible, or (as a last resort ) contact Raphael or Andreas.

About Ansible

Ansible is a command-line automation tool. The basic idea is to use yml files to configure what Ansible should to, and then use a make command on a Makefile to trigger the actual execution.

For our usage at GSI, that means that we have a project acoapp-ansible with yml files in which we configure which version of apps, services, etc. we want to roll out. Then we use a make command that works on a provided Makefile to trigger the actual rollout.

The provided Makefile provides "targets" to e.g. rollout a single artifact, a group of related artifacts (e.g. all applications), or all configured artifacts (e.g. all services, applications, LSA, ...). If you have ideas for additional "targets" or other additional functionality, please contact Raphael and Andreas about how to proceed to implement it!

How To Rollout Applications With Ansible

The following is a short explanation for how to rollout an application. The procedure is basically the same for e.g. rolling out app-services or lsa artifacts.

1. Get acoapp-ansible

• You must be working on the cluster (>= acc9, asl75x).
• Checkout acoapp-ansible (main branch).
• In the "inventories" folder, there are sub-folders for the different environments: "dev", "int", and "pro". They each contain a "groups-vars" folder, which contains the yml files for the specific environment.
• There are different yml files for different types/groups of artifacts, e.g. applications.yml, app_services.yml, lsa.yml, ...

2. Prepare rollout: Update the relevant yml file(s).

• Make sure that all artifacts you want to rollout are available in our Nexus artifact repository.
• Pull acoapp-ansible to get the latest state.
• Open the yml file(s) for the environment and group of artifacts for which you want to rollout something, e.g. the applications.yml under the "pro" inventory folder.
• Add a new entry for your artifact (please try to maintain the alphabetical order! ), or update the version information for the entry of your artifact.
  • For "dev" and "int", we usually want to rollout the appropriate snapshot version. This is handled by a variable ({{ env_version }}). You only need to specify an explicit version if you want to rollout a different version.
  • For "pro", you must specify the exact version you want to rollout. Usually, this should be a stable version (e.g. 18.0.7).
• Commit and push your changes.

Now you have prepared the rollout - it can now be performed using the make command.

If you skip the next step and do not perform the rollout yourself, rollout of your artifact may be performed by someone else at some later time - but there is no automatic rollout, and you cannot be sure whether/when someone else will do it for you!

3. Perform rollout using make

Execute the make command on the provided Makefile

• Pull acoapp-ansible to get the latest state.
• Open a terminal in the acoapp-ansible root directory.
• General hints
  • If you do not specify the ENV(ironment), "dev" is assumed.
• To rollout a single artifact:
  • Basic command: make [target] ENV=[environment] ANS_ARGS='-e "app_artifactid=[your_artifact_id]"'
  • Sample command: make applications ENV=pro ANS_ARGS='-e "app_artifactid=parammodi-app"'
  • Hints
    • All application developers should have the necessary permissions to perform this step.
• To rollout all applications:
  • Basic command: make [target] ENV=[environment]
  • Sample command: make applications ENV=pro
  • Hints
    • This takes a while.
    • Ansible will go through all artifacts of the specified target to see which artifacts actually have changed and need to be updated. Don't be alarmed at all the output.
    • All application developers should have the necessary permissions to perform this step.
• To rollout everything (all applications, app-services, lsa, ...)
  • Basic command: make ENV=[environment]
  • Sample command: make ENV=pro
  • Hints
    • This takes a while.
    • Ansible will go through all artifacts of the specified target to see which artifacts actually have changed and need to be updated. Don't be alarmed at all the output.
    • The APP team should have the necessary permissions to perform this step. People from other groups may not have all necessary permissions, and should specify more explicitly what they want to do (e.g. rollout only applications).

How to tell if your artifact has been rolled out

Sample output from Ansible for a single application:

PLAY [applications] ****************************************************************************************************************************************************************

TASK [Gathering Facts] *************************************************************************************************************************************************************
ok: [asl75a.acc.gsi.de]

TASK [apps : Download and deploy apps] *********************************************************************************************************************************************
[...]

TASK [apps : WebDAV - download checksum file my-app.checksum] **********************************************************************************************************
ok: [asl75a.acc.gsi.de]

TASK [apps : Create temporary directory for Artifacts my-app.zip.checksum] *********************************************************************************************
ok: [asl75a.acc.gsi.de]

TASK [apps : Artifacts - download my-app.zip.checksum to temp directory] ***********************************************************************************************
ok: [asl75a.acc.gsi.de]

TASK [apps : WebDAV - retrieve checksum from my-app.zip.checksum (/tmp/ansible.zem1isaq_artifact_checksum_temp)] *******************************************************
ok: [asl75a.acc.gsi.de]

TASK [apps : Creating temporary directory for Artifacts my-app.zip] ****************************************************************************************************
ok: [asl75a.acc.gsi.de]

TASK [apps : Artifacts - download my-app.zip to temporary directory] ***************************************************************************************************
ok: [asl75a.acc.gsi.de]

TASK [apps : WebDAV - delete "https://websvcpro.acc.gsi.de/groups/fcc/applications/my-app.zip.checksum"] ***************************************************************
changed: [asl75a.acc.gsi.de]

TASK [apps : WebDAV - upload to "https://websvcpro.acc.gsi.de/groups/fcc/applications/my-app.zip"] *********************************************************************
changed: [asl75a.acc.gsi.de]

TASK [apps : Removing temporary directory for Artifacts my-app.zip] ****************************************************************************************************
ok: [asl75a.acc.gsi.de]

TASK [apps : WebDAV - upload to "https://websvcpro.acc.gsi.de/groups/fcc/applications/my-app.zip.checksum"] ************************************************************
changed: [asl75a.acc.gsi.de]

TASK [apps : Removing temporary directory for WebDAV my-app.zip.checksum] **********************************************************************************************
ok: [asl75a.acc.gsi.de]

PLAY RECAP *************************************************************************************************************************************************************************
asl75a.acc.gsi.de          : ok=13   changed=3    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

The "recap" line is always printed at the very end, so even if you execute the rollout for multiple artifacts at once, you can get a quick overview how many artifacts where changed/skipped.

Manual Application Rollout / But I don't want to use Ansible!

The APP team recommends using the Ansible approach described above. This is the approach APP supports and can help you with, and it leads to a well-defined set of rolled out applications. Also, it's super-cool and shiny.

If you cannot or do not want to use our super-cool and shiny approach (boo!):

You can manually place your ZIP in https://websvcpro.acc.gsi.de/groups/fcc/applications_manually/, using e.g. thunar on the asl75x cluster and mounting davs://websvcpro.acc.gsi.de/groups/fcc/applications_manually/ .

• Note the _manually suffix for the folder name! Do not place it manually in /fcc/applications/: If you do,your app may be deleted or overwritten at any time.
• You are solely responsible for updating your manually rolled out applications.
• Make sure that the ZIP does not contain a version number etc. - the URL must remain the same, even when you manually rollout a new version!
• Contact the APP team with the following information if the URL in the launcher needs to be adapted after your first rollout to this location:
  • What is the name of your application in the launcher?
  • What is the full URL for the application?

-- AnnekeWalter - 24 Feb 2023