ForgeOps DS Script Guide 7.4/7.5

Setup
, , , , ,
#1

PURPOSE

This document provides an overview of the various scripts found in the docker/ds/ds-new folder in forgeops and at what point in the docker build or deployment process it is triggered. This overview is intended to help users understand the workflows and interactions between the different scripts.

DOCKER BUILD

Command: forgeops build ds --push-to=<my-docker-registry>
Actions:

  1. Builds docker/ds/ds-new/Dockerfile
  2. Adds docker/ds/ds-new/default-scripts for runtime tasks
  3. Adds docker/ds/ds-new/docker-entrypoint.sh for runtime tasks
  4. Adds docker/ds/ds-new/ds-setup.sh for initial skeleton DS setup(no backend setup)
  5. Runs docker/ds/ds-new/ds-setup.sh
  6. Pushes image to configured docker registry
  7. Updates kustomize/deploy/image-defaulter/kustomization.yaml with new image url.

RUNTIME SCRIPT CALLS

Command:

  • forgeops install -f <fqdn> or
  • forgeops install base ds (just DS for testing DS only)

Actions:

  1. Init container(init):
    a. Runs default-scripts/init-and-restore.sh
    b. Runsdocker-entrypoint.sh initialize-only to initialize DS
    c. Restores backup if required if a restore is correctly configured as described here.
  2. Main container(ds):
    a. Runs docker-entrypoint.sh start-ds to start the DS server

SCRIPT REFERENCE GUIDE

Click on the following links for more information about a script:

Build scripts
ds-setup.sh
docker-entrypoint.sh

Runtime scripts
default-scripts/backup
default-scripts/init-and-restore
default-scripts/post-init
default-scripts/restore
default-scripts/rstatus
default-scripts/setup
default-scripts/schedule-backup.sh

ds-setup.sh

Location: docker/ds/ds-new/ds-setup.sh
Url: https://github.com/ForgeRock/forgeops/blob/release/7.4-20240126/docker/ds/ds-new/ds-setup.sh

Purpose

ds-setup.sh runs at Docker build time and is called from the DS Dockerfile. The script runs a pre-setup by creating a skeleton DS instance that is ready for further customization with the runtime ā€˜setupā€™ script. After completion, a tar file is created with the contents of the setup. This tar file is kept as part of the docker image, and expanded at setup time to ā€œprimeā€ the PVC with the DS instance.

Functions/Steps

  1. Run the setup command using a newly provisioned Deployment ID.
  2. Set default global settings, create relevant log publishers and bootstrap servers.
  3. Relax some security settings required for ForgeOps deployments.
  4. Setup the PEM truststore provider.
  5. Update logger name in config.
  6. Remove the default admin and monitor account passwords.
  7. Create a tar of the data directory.
  8. Add custom configurations to the bundle setup profiles.(see customising DS section)

docker-entrypoint.sh

Location: docker/ds/ds-new/docker-entrypoint.sh
Url: https://github.com/ForgeRock/forgeops/blob/release/7.4-20240126/docker/ds/ds-new/docker-entrypoint.sh

Purpose

Entrypoint script which is triggered when the DS pod starts up

Entrypoint commands

initialize-only (init-container[init])

  • If there is data in the data directory, just run init:

    1. Upgrade data and rebuild indexes
    2. Set admin and monitor passwords to passwords provided in the ds-passwords k8s secret.

  • If there is no data in the data directory

    1. Untar setup tar created by ds-setup.sh during docker build phase
    2. Copy k8s secrets(PEM keystore/truststore) to the writable volume. See ds-setup.sh for PEM provider setup
    3. Run setup: Run setup script(forgeops/default-scripts/setup)
    4. Run init
      a. Upgrade data and rebuild indexes
      b. Set admin and monitor passwords to passwords provided in the ds-passwords k8s secret.

start-ds (main container[ds])

  1. Remove server lock
  2. Run start-ds

backup

(DS Operator only)

Location: docker/ds/ds-new/default-scripts/backup
Url: https://github.com/ForgeRock/forgeops/blob/release/7.4-20240126/docker/ds/ds-new/default-scripts/backup

Purpose

Sample backup script used by the DS Operator backup job

init-and-restore.sh

Location: docker/ds/ds-new/default-scripts/init-and-restore.sh
Url: https://github.com/ForgeRock/forgeops/blob/release/7.4-20240126/docker/ds/ds-new/default-scripts/init-and-restore.sh

Purpose

Used as DS init container command. Will attempt to automatically restore from a cloud backup if the relevant env vars are set. See the comments in the script for more details.

Functions/Steps

  1. Check if data is present in data directory.

  2. Run initialize-only step in the docker-entrypoint.sh.

  3. Checks var AUTORESTORE_FROM_DSBACKUP (set in platform-config configmap).

    1. Exits script if set to false or not set

  4. Configure the relevant cloud storage properties.

  5. Recover from the first available backup that passed verification checks.

  6. Run the setup-passwords-only function from docker-entrypoint.sh

post-init

Location: docker/ds/ds-new/default-scripts/init-and-restore.sh
Url: https://github.com/ForgeRock/forgeops/blob/release/7.4-20240126/docker/ds/ds-new/default-scripts/post-init

Purpose

Allows a customer to add custom configuration to DS. This script is run by the init container after index rebuilds are performed. This script can be used to add any new indexes before the server starts, or to issue any other dsconfig commands. The directory is offline when this script is run.

To configure ds-idrepo and ds-cts differently, see [Lifecycle scripts (TBD)

restore

(DS Operator only)

Location: docker/ds/ds-new/default-scripts/restore
Url: https://github.com/ForgeRock/forgeops/blob/release/7.4-20240126/docker/ds/ds-new/default-scripts/restore

Purpose

Sample restore script used by the DS Operator restore job

rstatus

Location: docker/ds/ds-new/default-scripts/rstatus
Url: https://github.com/ForgeRock/forgeops/blob/release/7.4-20240126/docker/ds/ds-new/default-scripts/rstatus

Purpose

Helper script that can be run manually to check the replication status of DS.

kubectl exec -it ds-idrepo-0 -- bash default-scripts/rstatus

setup

Location: docker/ds/ds-new/default-scripts/setup
Url: https://github.com/ForgeRock/forgeops/blob/release/7.4-20240126/docker/ds/ds-new/default-scripts/setup

Purpose

Default setup script. Setup the directory server for the idrepo and cts backends. The setup uses DS setup profiles.

Functions/Steps

  1. Run setup-profiles for backends.
  2. Create backend indexes.

schedule-backup.sh

Location: docker/ds/ds-new/default-scripts/schedule-backup.sh
Url: https://github.com/ForgeRock/forgeops/blob/release/7.4-20240126/docker/ds/ds-new/default-scripts/schedule-backup.sh

Purpose
Server side backup script that is manually triggered by bin/ds-backup.sh. This script takes variables set by the user in ds-backup.sh and triggers a dsbackup cron schedule with optional cloud bucket configuration. This script shouldnā€™t need to be edited.

Functions/Steps

  1. Validate and set all the user supplied environment variables.
  2. Cancel a running backup task if it matches the user supplied task name.
  3. Configure the relevant cloud storage properties.
  4. Add optional backends if supplied. Default = backup all backends.
  5. Run dsbackup command.
2 Likes