Deployment ========== The standard deployment of the ska-dlm-client within the SKA Kubernetes environment uses a set of Helm charts and an associated configuration file (`values.yaml `_). A full guide is given below. Clone the ska-dlm-client repository --------------------------------------- Begin by cloning the GitLab repository: .. code-block:: bash git clone --recurse-submodules https://gitlab.com/ska-telescope/ska-dlm-client.git .. _checkout_release: Retrieve the available release tags and check out the desired release: .. code-block:: bash cd ska-dlm-client git fetch --tags git tag --list git checkout .. note:: Before continuing, confirm that the DLM **server** service pods are running. See the `installation guide for DLM server `_ (*WIP*). Before deploying, verify that the running DLM server version is compatible with the dlm-client release you intend to deploy. Next, modify the ``values.yaml`` file as required. The sections below describe the configuration options most likely to require adjustment in typical deployments. Other values should generally be left at their defaults unless you have a specific reason to change them. .. Mention enums somewhere Shared ska-dlm-client values ---------------------------- - ``image``: Container image to use for all watcher components (e.g., ``artefact.skao.int/ska-dlm-client``). - ``version``: Image tag or version (e.g., ``"1.0.0"``). - ``imagePullPolicy``: Kubernetes image pull policy (e.g., ``Always``, ``IfNotPresent``) - ``securityContext``: Kubernetes context updated during deployment. Directory Watcher component --------------------------- - ``enabled``: Whether to deploy the ``directory-watcher`` component. - ``ingest_url``: Full HTTP URL of the ingest server. E.g., ```` - ``storage_url``: Full HTTP URL of the storage server. E.g., ```` - ``migration_url``: Full HTTP URL of the migration server. E.g., ```` - ``source_name``: Storage to monitor for new data. - ``directory_to_watch``: Directory to monitor for new data. - ``target_name``: Target storage (where new data will be migrated to, default dlm-archive) - ``target_root``: Target storage root directory. - ``uid_expiration_days``: Number of days from now until this UID expires. 0 = expire immediately. Leave empty to use DB default: now() + 24:00. - ``oid_expiration_days``: Number of days from now until this OID expires. Leave empty to use DB default: 2099-12-31T23:59:59. - ``use_polling_watcher``: false means using the iNotify-based watcher, which might not work with networked filesystems. - ``skip_rclone_access_check_on_register``: If ``true``, skips verifying rclone access before attempting to register the file. - ``include_existing``: If ``true``, registers & migrates all contents of the watch directory at startup, not just newly detected files. - ``pvc.name``: Name of the volume to mount into the directory-watcher pod. - ``pvc.read_only``: Set to ``true`` to limit the scope of what the directory-watcher can do. Needs to be ``false`` to allow for data deletion. - ``tolerations``: Optional list of Kubernetes pod tolerations for scheduling the directory watcher onto tainted nodes. - ``affinity``: Optional Kubernetes affinity configuration for scheduling the directory watcher onto specific nodes, for example where local storage is available. Startup Verification --------------------- - ``startup_verification``: Whether to enable startup verification. Keep ``false`` atm because this code is out of date. A ``startup verification`` can be enabled during the deployment of the watcher Helm chart. This will exercise the ``directory watcher`` by: - Adding a data item to the watch directory. - Giving the directory watcher a short amount of time to detect and register the data item. - Querying the DLM request service for the data item name. - Reporting a ``PASSED`` or ``FAILED`` response (based on the result) to the logs and exiting. To check the logs of the startup verification pod: .. code-block:: shell kubectl logs Sample output: .. code-block:: none 2025-04-21 13:08:33,187 - INFO - PASSED startup tests 2025-04-21 13:08:33,187 - INFO - Startup verification completed. If ``enabled.true``, need to specify the full HTTP URL of the request server, ``request_url`` (E.g., ````). ConfigDB Watcher component -------------------------- - ``enabled``: Whether to deploy the ``configdb-watcher`` component. - ``ingest_url``: Full HTTP URL of the ingest server. E.g., ```` - ``storage_url``: Full HTTP URL of the storage server. E.g., ```` - ``migration_url``: Full HTTP URL of the migration server. E.g., ```` - ``include_existing``: If true, registers & migrates all existing COMPLETED data-products found in the etcd DB at startup. - ``source_name``: Storage where the new data appears. - ``directory_to_watch``: Directory used to generate URIs for the DLM database. - ``target_name``: Target storage (where new data will be migrated to). Default is ``dlm-archive``. - ``uid_expiration_days``: Number of days from now until this UID expires. 0 = expire immediately. Leave empty to use DB default: now() + 24:00. - ``oid_expiration_days``: Number of days from now until this OID expires. Leave empty to use DB default: 2099-12-31T23:59:59. - ``pvc.name``: Name of the volume to mount into the configdb-watcher pod. - ``pvc.read_only``: Set to ``true`` to limit the scope of what the configdb-watcher can do. Needs to be ``false`` to allow for data deletion. - ``sdp_config.etcd_url``: Full URL of the external ConfigDB (etcd) service, for example ``http://my-etcd.other-namespace:2379``. To deploy a local etcd instance instead, leave this empty and set ``sdp_config.local_etcd.enabled`` to ``true``. - ``sdp_config.local_etcd.enabled``: Optionally enable a local etcd instance (for testing purposes). Kafka Watcher component (deprecated) ------------------------------------ The Kafka watcher is now **deprecated** (superseded by the ConfigDB Watcher). If you are working on an older release of the dlm-client, please set ``enabled: false``. .. _deploy-dlm-client: Deploy dlm-client ----------------- Once you have customised your ``values.yaml`` file, deploy dlm-client to a Kubernetes cluster (or a local Kubernetes environment) using: .. code-block:: shell helm upgrade --install ska-dlm-client [-n ] charts/ska-dlm-client If no namespace is specified, the default namespace associated with your current Kubernetes context will be used. Example Deployment ------------------ A `sample deployment configuration `_ is provided in the ``resources`` directory of the repository. This example is configured for deployment to the DP cluster. To deploy using this configuration: .. code-block:: shell helm install -f resources/dp-proj-user.yaml [-n ] ska-dlm-client charts/ska-dlm-client .. _uninstall-dlm-client: Uninstall the chart ------------------- To remove the dlm-client chart from the cluster: .. code-block:: shell helm uninstall [-n ] ska-dlm-client Troubleshooting (*WIP*) ----------------------- The following are common issues encountered during deployment and suggested resolutions. **Pods not starting or not syncing after configuration changes** If pods are not behaving as expected after modifying configuration values, it can help to uninstall and redeploy the chart to ensure all resources are recreated cleanly (see :ref:`uninstall-dlm-client`). After uninstalling, redeploy as described in :ref:`deploy-dlm-client`. Also ensure you are deploying the latest release. See :ref:`these instructions ` on retrieving the available release tags. **Helm dependency errors** If you see an error such as: :: Error: INSTALLATION FAILED: An error occurred while checking for chart dependencies. You may need to run `helm dependency build` to fetch missing dependencies. Try running ``helm dependency build charts/ska-dlm-client``.