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:
- Builds
docker/ds/ds-new/Dockerfile
- Adds
docker/ds/ds-new/default-scripts
for runtime tasks - Adds
docker/ds/ds-new/docker-entrypoint.sh
for runtime tasks - Adds
docker/ds/ds-new/ds-setup.sh
for initial skeleton DS setup(no backend setup) - Runs
docker/ds/ds-new/ds-setup.sh
- Pushes image to configured docker registry
- 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:
-
Init container(init):
a. Runsdefault-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. -
Main container(ds):
a. Runsdocker-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
- Run the setup command using a newly provisioned Deployment ID.
- Set default global settings, create relevant log publishers and bootstrap servers.
- Relax some security settings required for ForgeOps deployments.
- Setup the PEM truststore provider.
- Update logger name in config.
- Remove the default admin and monitor account passwords.
- Create a tar of the data directory.
- 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:
- Upgrade data and rebuild indexes
- Set admin and monitor passwords to passwords provided in the ds-passwords k8s secret.
-
If there is no data in the data directory
- Untar setup tar created by ds-setup.sh during docker build phase
- Copy k8s secrets(PEM keystore/truststore) to the writable volume. See ds-setup.sh for PEM provider setup
- Run setup: Run setup script(forgeops/default-scripts/setup)
- 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])
- Remove server lock
- 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
-
Check if data is present in data directory.
-
Run initialize-only step in the docker-entrypoint.sh.
-
Checks var AUTORESTORE_FROM_DSBACKUP (set in platform-config configmap).
- Exits script if set to false or not set
-
Configure the relevant cloud storage properties.
-
Recover from the first available backup that passed verification checks.
-
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
- Run setup-profiles for backends.
- 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
- Validate and set all the user supplied environment variables.
- Cancel a running backup task if it matches the user supplied task name.
- Configure the relevant cloud storage properties.
- Add optional backends if supplied. Default = backup all backends.
- Run dsbackup command.