Deployment manual | Anjana Data Documentación

Kit limitations

It is necessary to review this section to take into account the limitations when using the deployment kit.

The kit allows multiple machine inventories, but it is not able to manage multiple Anjana installations with different configurations. Multiple kits will be needed for different environments.
The machine where the kit is deployed must belong to a single Anjana environment, since it will be platformed and will undergo changes according to the Anjana environment being managed. It will not be possible to control multiple Anjana installations from a machine that contains the kit.
If the installation fails and relaunching the kit also fails, it will be advisable to reprovision the machine from scratch and start again.
The anjana user is a reserved user and cannot exist on the machine.

Requirements

Required connectivity

The kit will download all necessary resources from the Anjana Data central repository over HTTPS protocol and port 443 against the server releases.anjanadata.com, so connectivity from the servers to be provisioned to this service will be required.

It is necessary to request access and credentials from Anjana Data.

Environment platforming

As of 25.a1, a platforming script is included that will prepare the deployment machine intended for running the Anjana ansible kit with the following resources:

Download of the kit of the version indicated in the script itself.
Installation of the packages and dependencies needed for execution.

The script can be obtained here: anjana.sh

Once downloaded, it must be placed inside the machine to be platformed. It can be run using the following command:

chmod +x anjana.sh
./anjana.sh

The platforming script will require the following information:

Installation mode, new environment or existing Anjana environment.
Inventory, sample by default, but the inventory to be used will be specified even if it has not been created yet. It will NOT be possible to adjust it later by rerunning this script.
Credentials, requested beforehand from cs@anjanadata.com.
Domain, needed for the frontend and communication between microservices.
Certificate, corresponding to the chosen domain, in case you want to specify it manually.
Monitoring, to use the Open Telemetry Java instrumentation agent provided by the installer.
Version, by default the most recent one corresponding to the platforming script.

For RedHat, SELinux must be set to Permissive or Disabled.

As of 25.a2, the required certificate is generated automatically as a self-signed certificate by the installation.
If you want to use a public certificate, it needs to be placed in the /opt/common/anjana-certs/ directory on all the instances that make up the Anjana environment.

Required settings

The kit comes preconfigured to deploy Anjana according to the recommended settings; adjustments will need to be made depending on the environment according to the following guidelines:

The sample example inventory will be replaced during kit updates, so it should be used as a base to generate your own inventories before continuing.

Singlenode: For Singlenode environments, no modification or additional adjustments are required; the sample inventory provided in the kit can be used.

Distributed / Balanced: For Distributed or Balanced environments, or when you want to use a node other than the Anjana environment node as the ansible node, it will be necessary to use the provided sample inventory or generate a new one by cloning it in order to make the following adjustments:

Connection credentials to the infrastructure
anjana-platform nodes: the entry will need to be duplicated for each instance present in the environment, adjusting the numbering and IP, bearing in mind that localhost refers to the instance on which the ansible kit is running and does not need to be duplicated.

If the ansible kit has been placed outside the Anjana node and it is a Distributed environment, it is necessary to uncomment anjanaplatform2 and fill it in with the data of the core node.

Other nodes: will be adjusted according to the distribution of the environment and the descriptions in the file itself, indicating on each node the IP corresponding to the actual instance. Example of use: If there is more than one Zookeeper node, the entry must be duplicated.
All environments: Common to all types of environments, the license must be specified and adjusted in the corresponding section of the all.yaml file, located (by default) at /opt/ansible/ansible-inventories/<inventory>/group_vars/all.yaml.

To learn about all the available configurable options, you can consult Appendix - Advanced functionality.

If the Anjana environment is Distributed or Balanced, or the ansible kit has been placed outside the Anjana node, it is necessary to run the platform tag after making the necessary adjustments, in order to platform and configure all the deployment nodes.

An example hostsB.yaml file has been included, which contains the recommended number of nodes for a Balanced environment.

If you want to use it, you would only need to replace the original hosts.yaml with this one.

anjana -t platform

Anjana installation

After taking into account what was mentioned in the Requirements section, you will need to check whether additional adjustments are necessary, taking into account the Appendices Advanced functionality or Use Cases.

Once completed, to install Anjana, whether Singlenode, Distributed or Balanced, one of the following commands will be run:

To install Anjana with sample data:

anjana -t anjana-sample

To install Anjana without sample data:

anjana

Once the installation is finished, the Anjana Data frontends can be accessed via the configured domain:

example.anjanadata.org/

example.anjanadata.org/configpanel

Kit update and maintenance

Requirements

Required connectivity

It is assumed that you have the same connectivity mentioned previously in the Required connectivity section of the Anjana Deployment section.

General

It will be necessary to stop the Anjana environment using the anjana -t stop command as a step prior to updating the kit.
It will be necessary to remove the content of the previous Anjana command alias located in ~/.bash_aliases.

Ansible kit update

For updates from 25.1 or kit updates within version 25.a2, the following steps will be followed:

Running the platforming script

(25.a2x and earlier)

The platforming script includes an option to deploy on an existing environment, which allows the following actions to be carried out:

Removal of all existing ansible packages and subsequent installation of the updated ones.
Installation of the packages and dependencies needed for execution.
Backup of the existing kit, for its removal and download of the updated one.
Re-platforming of the node on which ansible is running (manager).

The platforming script will require the following information:

Installation mode, new environment or existing Anjana environment.
Inventory, sample by default, but the existing inventory will be specified. It will NOT be possible to adjust it later by rerunning this script.
Informational message about the changes, to confirm that the process should continue.
Credentials, requested beforehand from cs@anjanadata.com.
Domain, needed for the frontend and communication between microservices.
Certificate, corresponding to the chosen domain, in case you want to specify it manually.
Version, by default the most recent one corresponding to the platforming script.

After the script finishes, some help commands will be shown to continue with the update operation to 25.2.

Required inventory adjustments

It will be necessary to review the Required settings section of the Anjana Deployment section to find the missing steps that best fit the existing environment, whether Singlenode or Distributed/Balanced.

Configuration migration

(25.a2x and earlier)

In some cases it will be necessary to migrate the customizations from the previous kit configuration to the new installation, taking into account the following points to review.

In all.yaml:

Nexus access credentials
Persistence credentials (Solr, PostgreSQL/RDS, MinIO/S3)
Persistence hosts and ports (Solr, PostgreSQL/RDS, MinIO/S3)
Security update settings

As of 25.a2, every time the connection strings in all.yaml are modified, it will be necessary to re-platform in order to generate the updated environment variables file using the anjana -t platform command.

In hosts.yaml:

Connection credentials for instances.
IPs and/or domains belonging to the environment's instances.

In anjanauihosts.yaml:

apache2 security settings
Whitelist settings and entries

In templates:

Credentials in plugins.
Customizations in core and plugin configuration.
Customizations in core and plugin descriptors.
Customizations in apache2 configuration.

In 25.a2, all necessary configuration has been internalized within the microservices themselves.

Customizations outside the options managed by the kit that are not strictly necessary for the configuration and service descriptors of the Anjana core as well as its frontends (apache2) are discouraged.

Ansible kit maintenance

Version matrix

To record the versions installed in an environment, the /opt/version-report file is available by default.

Logs

To record kit activity, the /opt/deployment.log file can be accessed by default.

The file records the actions and modifications carried out in the environment; an example follows below:

Anjana update and maintenance

Anjana update

The Anjana update can be carried out by running the following command:

anjana -t update

By default, it will look for new versions available for the product version chosen in all.yaml.

Specific versions can be set if you want to pin a microservice to a particular one, by specifying the microservice version.

Anjana maintenance

Import/deployment of roles and configuration

You can customize which roles you want to import by editing the import_role section in all.yaml and setting to true everything you want to import/deploy.

This way, plugins or microservices can be added later, along with their respective configurations. After adjusting the file, the configurations would be applied with:

anjana -t update-config

And the installation of microservices/plugins with:

anjana -t <microservicio>
anjana -t <plugin>

Configuration and services

It is possible to update and/or deploy the configuration of the microservices as well as their descriptors whenever changes are made and it is necessary.

The utility will deploy only the configurations and/or descriptors of the roles that are marked for import in all.yaml, import_role section, as indicated in the previous section Import/deployment of roles and configuration.

To deploy microservice and plugin configurations, run the following tag:

anjana -t update-config

To deploy frontend and apache2 configurations:

anjana -t update-vhosts

To deploy service descriptors:

anjana -t update-services

Starting, stopping, and restarting the environment

It is possible to start and stop the microservices selectively and in an orderly manner, thereby avoiding errors resulting from stopping a microservice without taking its dependencies into account.

Example of use: stopping the backend to perform an Anjana upgrade.

The utility is compatible with multiple instances of the same microservice (e.g.: horus1, horus2, kerno1, kerno2, etc.) but it cannot stop the duplicated instances individually. Selecting the stop for kerno will stop kerno1 and kerno2 respectively.

The functionality provided by this utility is as follows:

Orderly stopping and starting of all of anjana. It happens in the proper order to avoid unintended exceptions.

anjana -t stop
anjana -t start
anjana -t restart

Selective stopping and starting of a specific microservice. All the microservices necessary for the selected one to work will be started. In the case of stopping, all microservices that depend on the selected one will be stopped before it is stopped.

anjana -t stop-kerno
anjana -t start-kerno

Backups and restoration

Allows backups to be made at the path indicated in the backup variable of each role, by default /opt/backups, of all persistences and the configuration.

By default, during tasks that involve operations with the data, or during updates, backups are performed automatically.

To perform manual backups, the following commands can be run:

anjana -t backup
anjana -t backup-persistences
anjana -t backup-config

It is possible to restore the persistence data and the configuration using the restore tag or its respective individual tags:

anjana -t restore
anjana -t restore-s3
anjana -t restore-bbdd
anjana -t restore-config

Data migration

It is possible to export and import persistence data for a transfer between machines/environments.

By default, the export and import paths are /opt/export-import.

It is necessary to set installation.mode: manager in the all.yaml file for this utility.

Connection strings such as ports, host, passwords, S3 client type, among others, for databases and MinIO and Solr can be found and edited in the inventory's all.yaml file.

It should be noted that the generated files will be placed on the manager node, where ansible is running.

To export all data, use the command:

anjana -t export

If you want to include the configuration as part of the export and generate a compressed file:

anjana -t clone

Similarly, for import, the import tag or its corresponding individual tags are used:

anjana -t import
anjana -t import-s3
anjana -t import-bbdd

In the case of compressed data generated using the clone tag, the deploy tag and its corresponding individual tags would be used to import it:

anjana -t deploy
anjana -t deploy-s3
anjana -t deploy-bbdd
anjana -t deploy-config

Status check

The ability to check the health status of all the microservices, persistences and plugins included in the environment has been added, via an endpoint located at /status.

When querying it, we can obtain information such as the following:

Recommended for quickly finding the point of failure in the application. For a more precise search, it will be necessary to check the logs of the affected microservice, plugin, or persistence.

Exporting microservice logs

It is possible to export the Anjana microservice logs to the folder on each backend node, by default /opt/anjana-logs/<microservice>.log.

Recommended for providing logs to the support team.

For the export, you would need to run:

anjana -t export-log

By default, the last 5 days are exported, but this is configurable at runtime:

anjana -t export-log -e '{"log": {"since": "2 day ago"}}'

The logs can be uploaded to the S3 service or server configured in all.yaml; by default they are uploaded to the anjanalogs bucket using the command:

anjana -t export-log-s3

It is necessary to set installation.mode: manager or local in the all.yaml file for this utility.

Uninstallation

A utility is included for the complete uninstallation of the product for the selected inventory.
The uninstallation respects the backups, export-import, ansible directories and the installation log files version-report and deployment.log, both located in the main Anjana folder (by default /opt).
To uninstall Anjana, run the following command:

anjana -t uninstall

For the uninstallation to proceed correctly, the inventory and its hosts.yaml file must be up to date according to the current environment, including: active machines, IPs, hostnames, ssh connection user, etc…