Application deployment with Ansible

zpk2ansible is a command-line utility that builds a human-readable Ansible playbook based on a Zend Package (ZPK) to deploy the application to a server. You use it when migrating to ZendPHP from Zend Server. The tool is written in Python.

This article includes references to a third-party product, Ansible. The user interface and usage of third-party products are subject to change without notice. For the latest published information about Ansible, see docs.ansible.com.

Supported operating systems

The zpk2ansible tool is supported on the following operating systems:

• Linux
  For more information about supported Linux platforms, see Supported Platforms.

• IBM i

Requirements

• Knowledge of Ansible is required.
• ansible-core version 2.11 or later is required; this version includes the ansible.builtin.split filter which is used by the zpk2ansible tool.
• Python is required to use the optional venv environment.

Set up and install zpk2ansible

Our examples installs zpk2ansible into an optional Python virtual environment.

1. Set up a Python virtual environment to run the utility:

   Copy

   $ sudo apt install python3-pip python3-venv
   $ python -m venv venv
   $ source venv/bin/activate

2. Install the zpk2ansible utility inside the venv environment:

   Copy

   $ wget https://repos.zend.com/zpk2ansible/zpk2ansible-latest.tar.gz
   $ venv/bin/pip install ./zpk2ansible-latest.tar.gz
   $ venv/bin/zpk2ansible --version

Deploy your application

1. Create an inventory.yml file that describes the targets to which you are deploying your application. For more information, see How to build your inventory (Ansible Community Documentation).

   If the playbook contains the option hosts: all, ensure that the inventory.yml file contains only the hosts where the application will be deployed.

2. Inspect the ZPK file:

   Copy

   $ venv/bin/zpk2ansible inspect path/to/your/zpkFile.zpk

   The output for this command will include various details for the given ZPK file, dependencies, status of existing webserver vhost and PHP-FPM pool configurations, overridable parameters, and a sample build command for playbook generation. In case of an invalid ZPK file, the inspect command notifies you of what the invalid directory or file is.

   In addition to specifying the interactive mode or the chosen web server, this sample command demonstrates how you can override variables in the ZPK file. Find further information on these variables by running the following command:

   Copy

   $ venv/bin/zpk2ansible build --help

3. Build the playbook:

   Copy

   $ venv/bin/zpk2ansible build path/to/your/zpkFile.zpk vhost_name

4. Run the playbook:

   Copy

   $ ansible-playbook -i inventory.yml playbook.yml

Store your ZendPHP repository credentials

To ensure that you can access the ZendPHP repository safely, store your credentials securely. To store your ZendPHP repository credentials, pass them as extra variables when executing the playbook:

$ ansible-playbook -i inventory.yml playbook.yml --extra-vars "zendphp_repo_account=ORDER_ID zendphp_repo_password=PASSWORD"

You must store your credentials only once. If the playbook is executed a second time against the same target server, the playbook uses the credentials that are stored there.

To change the stored credentials, pass new credentials as extra variables when executing the playbook.

Configure a custom web server or PHP-FPM

To meet the specific requirements of your organization, you can configure a custom web server or PHP-FPM Pool. In this case, provide a custom web server vhost (Nginx and httpd) or PHP-FPM Pool configuration templates.

After you generate the playbook, the zpk2ansible utility creates several template files in the same directory where the playbook.yml file is:

• nginx.conf.j2 — the Nginx vhost configuration

• httpd.conf.j2 — the httpd vhost config

• fpm_pool.conf.j2 — the PHP-FPM pool configuration

How customization works:

• If you customize these templates, the tool uses your configuration template files when you run the generated Ansible playbook.

• If any of these template files are present in the playbook directory, they won't be overwritten.

• If any of these template files are missing from the playbook directory, the zpk2ansible tool checks first for the file in the ZPK package root directory.

  • If the file is not found in the root directory, the tool uses the included default file.

Usage examples

Prepare for deployment (quickstart method)

1. Edit the inventory:

   Copy

   $ nano inventory.yml

2. Edit the playbook. For example, add your ZendPHP repo credentials or a vhost name to the playbook.

   Copy

   $ nano playbook.yml

Create a deployment from a ZPK file

You can deploy a ZPK file to different web servers. Use one of the following commands:

To create a deployment for httpd 2.2, which is the default, create the playbook using the following command:

$ venv/bin/zpk2ansible build --httpd myapp.zpk vhost_name

To create a deployment for httpd 2.4, create the playbook using the following command:

$ venv/bin/zpk2ansible build --webserver_type httpd-2.4 myapp.zpk vhost_name

To create a deployment for nginx, create the playbook using the following command:

$ venv/bin/zpk2ansible build --nginx myapp.zpk vhost_name

Deploy with runtime playbook variables

To deploy the application with custom runtime playbook variables, use the following syntax:

$ ansible-playbook -i inventory.yml playbook.yml --extra-vars '{"VAR_NAME": "VALUE", "OTHER_VAR": "OTHER_VALUE"}'

You can override the following existing playbook variables:

• In nginx.conf.j2 and httpd.conf.j2:

  • vhost_name

  • docroot

  • fpm_socket_path

• In fpm_pool.conf.j2:

  • vhost_name

  • user

  • fpm_socket_path

  • web_server_user

Roll back a deployment

When you use zpk2ansible to generate a deployment playbook for a ZPK package, a corresponding rollback playbook is also created. Both playbooks include the application version number, which is defined in the deployment.xml file inside the ZPK package.

How rollback works

Each time you generate playbooks from a new version of a ZPK package, a new set of deployment and rollback playbooks is created with updated version numbers. To roll back to a previous version, run the rollback playbook that corresponds to the version you want to restore.

ZendPHP maintains all deployed versions internally. When you initiate a rollback, the system updates the symbolic link to point to the selected version.

Hook scripts

To support custom actions during rollback, the rollback playbook can run two optional scripts:

• pre_rollback.php: Runs before the symbolic link is updated

• post_rollback.php: Runs after the symbolic link is updated

These scripts must be located in the application directory of the version you are rolling back to.

Best practices

• Versioning: To enable rollback for new application versions, update the version number in the ZPK package and regenerate the playbooks.

• Retention: Keep all previously generated playbooks. This ensures you can roll back to any earlier version if needed.

• Hook script location: Ensure that pre_rollback.php and post_rollback.php scripts are present in the source directory of the target rollback version.