ForgeOps DS Customization Guide 7.4/7.5

Setup
, , , , , ,
#1

Overview

This document provides sets of instructions explaining how to customize and manage your DS deployment when deployed into a Kubernetes environment using ForgeOps. The use cases below are some of the more common use cases required by a majority of users and should help bridge the gap between tasks that users often know how to execute in an on-prem DS deployment but don’t know how to achieve the same outcome with a ForgeOps deployment.

NOTE: Any references to the forgeops repository or documentation is based on 7.4. The functionality for all use cases are the same for 7.5 and will be changed once 7.5 is released.

HELM: The following examples are based on Kustomize deployments using bin/forgeops. Helm deployments are available as a technology preview in 7.4. See the forgeops documentation for more details.

VIEWING THE LDAP DIRECTORY USING APACHE DIRECTORY STUDIO

  1. Download and open Apache Directory Studio

  2. Retrieve your DS admin password from the ds-passwords Kubernetes secret:
    kubectl get secret ds-passwords -o yaml |grep dirmanager.pw | cut -d' ' -f4 |base64 -d

  3. Port forward to your DS server on your terminal
    kubectl port-forward ds-idrepo-0 1389

  4. Configure Apache Directory Studio to connect to your DS server:
    a. Create a new LDAP connection
    b. Complete the Network Parameter tab as follows:

    image
    image1050×346 37.1 KB

    c. Update the Authentication tab with the Bind DN and the password your retrieved in step 2 and click on Check Authentication to verify that the connection is successful:

    image

  5. Click on your new LDAP connection to bring up the LDAP browser or right click to view option to open schema browser.

ADDING CUSTOM LDAP CONFIGURATION

Custom LDAP configuration can be included in your DS image by adding your custom ldif files to the docker/ds/ds-new/ldif-ext directory. This directory has been separated into subdirectories for each backend so just drop your ldif files into the relevant directory and rebuild the DS image:

  1. Build your DS image e.g.
    forgeops build ds --tag <tag name>

  2. Deploy DS.
    forgeops install
    or you can test DS only by running
    forgeops install base ds

  3. Validate your changes by attaching an ldap directory viewer to view the LDAP changes.

IMPORTANT These changes can only be made to a fresh deployment of DS.
If you want update the image on an already running deployment, ensure you delete the PVC prior to redeploying DS.
If you want to update DS without downtime, then follow the steps in the “Online LDAP updates” section below

Online LDAP updates
To update the LDAP confguration entries online without restarting DS, use the ldapmodify command but also make sure that your maintain the same custom LDAP configuration changes in your forgeops repo for future deployments.

ADDING CUSTOM LDAP SCHEMA

LDAP schema is configured in the upstream DS image and not in forgeops. But you can include custom schema changes by following the below steps:

  1. Navigate to docker/ds/ds-new/config/schema. All custom schema files should be added here. There is a sample file in this location to use as a starting point.

  2. Create your custom schema file here.

  3. Build your DS image
    forgeops build ds --tag <tag name>

  4. Deploy DS.
    forgeops install
    or you can test DS only by running
    forgeops install base ds

  5. Validate your changes by attaching an ldap directory viewer to view the schema.

IMPORTANT These changes can only be made to a fresh deployment of DS.
If you want update the image on an already running deployment, ensure you delete the PVCs prior to redeploying DS.
If you want to update DS without downtime, then see the “Online schema changes” section below.

Online schema changes
To update the schema on a running server, follow the commands in the DS documentation but also make sure that your maintain the same custom schema changes in your forgeops repo for future deployments.

USING LIFECYCLE SCRIPTS TO CUSTOMIZE IDREPO AND CTS SEPARATELY

By default, forgeops offers a single DS docker image that is consumed by both idrepo and cts pods. Therefore making changes to the DS docker image changes both the behaviour of idrepo and cts. In most cases this is sufficient as AM and IDM use only the backends that it needs. But sometimes users want to configure the behaviour differently for idrepo or cts. This can be done by configuring custom lifecycle scripts(these are the runtime scripts in docker/ds/ds-new/default-scripts and adding them to a configmap. See the readme for more details: https://github.com/ForgeRock/forgeops/blob/release/7.4-20240126/docker/ds/ds-new/README.md#default-scripts--life-cycle-hooks

Helm Steps

  1. Add your custom lifecycle scripts to a dedicated directory. If you are adding custom lifecycle scripts for both idrepo and cts, then you would need separate directories for each. There are already sample directories under forgeops/charts/identity-platform/files/lifecycle-scripts/ds which you can use or duplicate. These sample locations are set as default in the values.yaml.

  2. Enable lifecycle scripts in your values file for:

    idrepo:

      idrepo.lifecycleScripts.enabled: true
  idrepo.lifecycleScripts.path: </path/to/dir/containing/custom-scripts>

    cts:

      cts.lifecycleScripts.enabled: true
  cts.lifecycleScripts.path: </path/to/dir/containing/custom-scripts>

Kustomize Steps

  1. Create a configmap for each ds server you want use custom scripts for:

    • idrepo:

      kubectl create configmap ds-idrepo-lifecycle-scripts --from-file=/path/to/lifecycle-scripts/idrepo/setup

    • cts:

      kubectl create configmap ds-cts-lifecycle-scripts --from-file=/path/to/lifecycle-scripts/idrepo/setup

  2. Configure your overlay to patch the relevant volumes and volume mounts to DS

    e.g. ds-idrepo patch in <path/to/custom-overlay>/ds-idrepo.yaml

apiVersion: apps/v1
kind: StatefulSet
metadata:
 name: ds-idrepo
spec:
 replicas: 1
 template:
   spec:
     containers:
     - name: ds
       volumeMounts:
       - mountPath: /opt/opendj/scripts
         name: lifecycle-scripts
     initContainers:
     - name: init
       volumeMounts:
       - mountPath: /opt/opendj/scripts
         name: lifecycle-scripts
     volumes:
       - name: lifecycle-scripts
         configMap:
           name: ds-idrepo-lifecycle-scripts
           defaultMode: 0755

Validation

Check your updated scripts have run by viewing the logs
kubectl logs ds-idrepo-0 -c init
kubectl logs ds-cts-0 -c init

ADDING CUSTOM BACKENDS

TODO

1 Like