Layering server profiles ¶
One of the benefits of our Docker images is the ability to layer product configuration. By using small, discrete portions of your configuration, you can build and assemble a server profile based on multiple installations of a product.
A typical organization can have multiple installations of our products, each using different configurations. By layering the server profiles, you can reuse the configurations that are common across environments, leading to fewer configurations to manage.
You can have as many layers as needed. Each layer of the configuration is copied on top of the container's filesystem (not merged).
Layer Precedence
The profile layers are applied starting at the top layer and ending at the base layer. This might not be apparent. In our examples, the base profile layer appears first in the docker-compose.yaml
file. In these cases, it's a child-before-parent order of application.
Before you begin ¶
You must:
- Complete Get Started to set up your DevOps environment and run a test deployment of the products.
About this task ¶
You will:
- Create a layered server profile.
- Assign the environment variables for the deployment.
- Deploy the layered server profile.
Creating a layered server profile ¶
We'll use PingFederate and our server profile located in the pingidentity-server-profiles repository. You should fork this repository to your Github repository, then pull your Github repository to to a local directory. When you've finished creating the layered profile, you can push your updates the your Github repository and reference your Github repository as an environment variable to run the deployment.
We'll create separate layers for:
- Product license
- Extensions (such as, Integration Kits and Connectors)
- OAuth Playground
For this example, these layers will be applied on top of the PingFederate server profile. However, you can span configurations across multiple repositories if you want.
You can find the complete working, layered server profile of the PingFederate example you're building here in the pingidentity-server-profiles/layered-profiles directory.
Because PingFederate's configuration is file-based, the layering works by copying configurations on top of the PingFederate container’s file system.
Files Copied
Files are copied, not merged. It's best practice to only layer items that won't be impacted by other configuration files.
Creating the base directories ¶
Create a working directory named layered_profiles
and within that directory create license
, extensions
, and oauth
directories. When completed, your directory structure should be:
└── layered_profiles
├── extensions
├── license
└── oauth
Constructing the license layer ¶
- Go to the
license
directory and create apingfederate
subdirectory. -
Create the PingFederate license file directory path under the
pingfederate
directory.The PingFederate license file resides in the
/instance/server/default/conf/
path.mkdir -p instance/server/default/conf/
Your license profile path should look like this:
└── license └── pingfederate └── instance └── server └── default └── conf └── pingfederate.lic
-
Copy your
pingfederate.lic
file tolicense/pingfederate/instance/server/default/conf
.If you're using the DevOps evaluation license, when the PingFederate container is running, you can find the license in the Docker file system's
/opt/out/instance/server/default/conf
directory.You can copy the
pingfederate.lic
file from the Docker file system using the syntax:docker cp <container> <source-location> <target-location>
For example:
docker cp \ pingfederate \ /opt/in/instance/server/default/conf/pingfederate.lic \ ${HOME}/projects/devops/layered_profiles/license/pingfederate/instance/server/default/conf
If you're using the
ping-devops
tool:ping-devops generate license pingfederate > \ ${HOME}/projects/devops/layered_profiles/license/pingfederate/instance/server/default/conf
Building the extensions layer ¶
- Go to the
layered-profiles/extensions
directory and create apingfederate
subdirectory. -
Create the PingFederate extensions directory path under the
pingfederate
directory.The PingFederate extensions reside in the
/instance/server/default/deploy
path.mkdir -p instance/server/default/deploy
-
Copy the extensions you want to be available to PingFederate to the
layered-profiles/extensions/pingfederate/instance/server/default/deploy
directory .The extensions profile path should look similar to the following even though extensions vary based on your requirements:
└── extensions └── pingfederate └── instance └── server └── default └── deploy ├── pf-aws-quickconnection-2.0.jar ├── pf-azure-ad-pcv-1.2.jar └── pf-slack-quickconnection-3.0.jar
Building the OAuth layer ¶
-
Go to the
layered-profiles/oauth
directory and create apingfederate
subdirectory.mkdir -p instance/server/default/pingfederate
-
Copy the
OAuthPlayground.war
file to thelayered-profiles/oauth/pingfederate/instance/server/default/deploy
directory.Like other extensions, you can find the OAuth Playground for PingFederate in the
/instance/server/default/deploy
directory. For this example, you're building the OAuth Playground into its own layer to show that it's optional for PingFederate deployments.Your OAuth profile layer should look like this:
└── oauth └── pingfederate └── instance └── server └── default └── deploy └── OAuthPlayground.war
Assigning environment variables ¶
Although this deployment assigns the environment variables for use in a Docker Compose YAML file, you can use the following technique with any Docker or Kubernetes deployment.
If you want to use your Github repository for the deployment in the following examples, replace:
SERVER_PROFILE_URL=https://github.com/pingidentity/pingidentity-server-profiles.git
with:
SERVER_PROFILE_URL=https://github.com/<your-username>/pingidentity-server-profiles.git
Private Github Repo
If your GitHub server-profile repo is private, use the username:token
format so the container can access the repository. For example, https://github.com/<your_username>:<your_access_token>/pingidentity-server-profiles.git
. For more information, see Using Private Github Repositories.
- Create a new
docker-compose.yaml
file. -
Add your license profile to the YAML file.
For example:
- SERVER_PROFILE_URL=https://github.com/pingidentity/pingidentity-server-profiles.git - SERVER_PROFILE_PATH=layered-profiles/license/pingfederate
SERVER_PROFILE
supportsURL
,PATH
,BRANCH
andPARENT
variables. -
Using
SERVER_PROFILE_PARENT
, instruct the container to retrieve its parent configuration by specifying theextensions
profile as the parent:- SERVER_PROFILE_PARENT=EXTENSIONS
SERVER_PROFILE
can be extended to reference additional profiles. Because we specified the license profile's parent asEXTENSIONS
, we can extendSERVER_PROFILE
by referencing theEXTENSIONS
profile (prior to theURL
andPATH
variables):- SERVER_PROFILE_EXTENSIONS_URL=https://github.com/pingidentity/pingidentity-server-profiles.git - SERVER_PROFILE_EXTENSIONS_PATH=layered-profiles/extensions/pingfederate
-
Set the
EXTENSIONS
parent toOAUTH
:- SERVER_PROFILE_EXTENSIONS_PARENT=OAUTH
Then set the
URL
andPATH
for theOAUTH
profile:- SERVER_PROFILE_OAUTH_URL=https://github.com/pingidentity/pingidentity-server-profiles.git - SERVER_PROFILE_OAUTH_PATH=layered-profiles/oauth/pingfederate
-
Set
GETTING_STARTED
as theOAUTH
parent and declare theURL
andPATH
:- SERVER_PROFILE_OAUTH_PARENT=GETTING_STARTED - SERVER_PROFILE_GETTING_STARTED_URL=https://github.com/pingidentity/pingidentity-server-profiles.git - SERVER_PROFILE_GETTING_STARTED_PATH=getting-started/pingfederate
Because the
GETTING_STARTED
profile is the last profile to add, it won't have a parent.Your
environment
section of thedocker-compose.yaml
file should look similar to this:environment: # **** SERVER PROFILES BEGIN **** # Server Profile - Product License - SERVER_PROFILE_URL=https://github.com/pingidentity/pingidentity-server-profiles.git - SERVER_PROFILE_PATH=layered-profiles/license/pingfederate - SERVER_PROFILE_PARENT=EXTENSIONS # Server Profile - Extensions - SERVER_PROFILE_EXTENSIONS_URL=https://github.com/pingidentity/pingidentity-server-profiles.git - SERVER_PROFILE_EXTENSIONS_PATH=layered-profiles/extensions/pingfederate - SERVER_PROFILE_EXTENSIONS_PARENT=OAUTH # Server Profile - OAUTH - SERVER_PROFILE_OAUTH_URL=https://github.com/pingidentity/pingidentity-server-profiles.git - SERVER_PROFILE_OAUTH_PATH=layered-profiles/oauth/pingfederate - SERVER_PROFILE_OAUTH_PARENT=GETTING_STARTED # Base Server Profile - SERVER_PROFILE_GETTING_STARTED_URL=https://github.com/pingidentity/pingidentity-server-profiles.git - SERVER_PROFILE_GETTING_STARTED_PATH=getting-started/pingfederate # **** SERVER PROFILE END ****
Deploying the layered profile ¶
- Push your profiles and updated
docker-compose.yaml
file to your GitHub repository. - Deploy the stack with the layered profiles.
To view this example in its entirety, including the profile layers and docker-compose.yaml
file, see the pingidentity-server-profiles/layered-profiles directory.