Using Release Tags ¶
Ping Identity uses multiple tags for each released image. On our Docker Hub site, you can view the available tags for each image.
Multi-product deployment
All product containers in a deployment should use the same release tag.
Store images privately ¶
Before discussing tags, it is important to know more about Ping Identity's use of Docker Hub for images. While Docker Hub is very reliable and you can always find the latest images of Ping Identity products hosted there, do not rely on Ping to maintain Docker images in Docker Hub over time. See the image support policy for details.
To ensure continued access to any image, pull the image in question and maintain it in your own image registry. Common Docker registry providers include: JFrog, AWS ECR, Google GCR and Azure ACR.
Tagging Format ¶
To specify a release tag for deployments, use the following format:
image: pingidentity/<ping-product>:${PING_IDENTITY_DEVOPS_TAG}
In the example above, <ping-product> is the name of the product and ${PING_IDENTITY_DEVOPS_TAG} is the assigned release tag value. The file containing the setting for ${PING_IDENTITY_DEVOPS_TAG} is ~/.pingidentity/config by default. This file is created by running the pinctl config command, documented here. You can also specify the release tag explicitly in your deployments. The release tag must be the same for each container in the deployment. For example:
image: pingidentity/<ping-product>:edge
Determine Which Tag To Use ¶
The tag to use depends on the purpose of the deployment in question. Along with using a tag, any image on Docker Hub can be referenced using the SHA256 digest to ensure immutability in your environments. The digest for a given image never changes regardless of any tag or tags with which it is associated.
Production Stability ¶
For customers in production environments, stability is often the highest priority. To ensure a deployment with the fewest dependencies and highest product stability:
-
Use the digest of a full sprint tag that includes the sprint version and product version. For example, consider the image tag
pingidentity/pingfederate:2206-11.1.0. To pull this image using the corresponding digest:docker pull pingidentity/pingfederate@sha256:8eb88fc3345d8d71dafd83bcdcc38827ddb09768c6571c930b4d217ea177debf
Latest Image Features ¶
For demonstrations and testing latest features, use an edge based image. In these situations, it is a good practice to use a full tag variation similar to pingfederate:11.1.0-edge, rather than simply pingfederate:edge. Doing so avoids dependency conflicts that might occur in server profiles between product versions (for example, 10.x versus 11.x).
Evergreen Bleeding Edge ¶
The edge is the absolute latest product version and image features, with zero guarantees for stability.
Typically, this tag is only of interest to Ping employees and partners.
Base Release Tags ¶
The base release tags for a product image build are:
- edge
- latest
- sprint
edge ¶
The edge release tag refers to "bleeding edge", indicating a build similar to an alpha release. This sliding tag includes the latest hooks and scripts, and is considered highly unstable. The edge release is characterized by:
- Latest product version
- Latest build image enhancements and fixes from our current sprint in progress
- Linux Alpine as the container base OS
Example: pingidentity/pingfederate:edge, pingidentity/pingfederate:11.1.0-edge
latest ¶
edgeis tagged as latest at the beginning of each month. The release tag indicates the latest stable release. This tag is also a sliding tag that marks the stable release for the latest sprint. The latest release is characterized by:
- Latest product version
- All completed and qualified enhacements and fixes from the prior monthly sprint
- Linux Alpine as the container base OS
Example: pingfederate:latest, pingfederate:11.1.0-latest
sprint ¶
In addition to becoming latest, edge also is tagged as a stable sprint each month. The sprint release tag is a build number indicating a stable build that will not change over time. The sprint number uses the YYMM format. For example, 2208 = August 2022. The sprint release is characterized by:
- Latest product version at the time the sprint ended.
- All completed and qualified enhancements and fixes from the specified monthly sprint. The Docker images are generated at the end of the sprint.
- Linux Alpine as the container base OS
Example: pingfederate:2206, pingidentity/pingfederate:2206-11.1.0
sprint (point release) ¶
Occasionally, a bug might be found on a stable release, whether in the product itself or something from the team building the image. In these situations, to avoid changing a sprint tag which is promised to be immutable, a point release would be created to move latest forward.
Example only
These example tags do not exist, they are used here only for illustration purposes.
Example: pingfederate:2206.1, pingidentity/pingfederate:2206.1-11.1.0
Determine Image Version ¶
If you are unsure of the exact version of the image used for a given product container, shell into the container and examine the $IMAGE_VERSION environment variable. For example, if you are running a container locally under Docker, you would run the following commands:
docker container exec -it <container id> sh
echo $IMAGE_VERSION
The IMAGE_VERSION variable returns the version in this format:
[product]-[container OS]-[jdk]-[product version]-[build date]-[git revision]
For example:
IMAGE_VERSION=pingdirectory-alpine_3.16.0-al11-9.1.0.0-220725-c917
Where:
| Key | Value |
|---|---|
| Product | pingdirectory |
| Container OS | alpine_3.16.0 |
| JDK | al11 |
| Product Version | 9.1.0.0 |
| Build Date | 220725 |
| Git Revision | c917 |
If the container is running under Kubernetes, use the kubectl exec command to access the container in order to obtain this information.
Date Format
In the $IMAGE_VERSION variable, Date is in YYMMDD format