Helm Basics ¶
Although this document cannot cover the depths of this tool, brand-new Helm users might find other technical documentation too involved for Ping Identity DevOps purposes. This document aims to equip new users with helpful terminology in simple terms, with a focus on relevant commands. For more in-depth documentation around Helm, check out helm.sh.
This overview uses Ping Identity DevOps as a guide, but the principles will apply to any typical interaction with Kubernetes. As a result, this document might feel incomplete or inaccurate to Helm veterans. If you would like to contribute, feel free to open a pull request!
Ping Identity DevOps and Helm
All of our instructions and examples are based on the Ping Identity DevOps Helm chart. If you are not using the Ping Identity DevOps Helm chart in production, we still recommend using it to generate your direct Kubernetes manifest files. Using our provided chart to create your files in this manner gives Ping Identity the best opportunity to support your environment.
Everything in Kubernetes is deployed by defining what you want and allowing Kubernetes to achieve the desired state (the declarative model).
Helm simplifies your interaction by building deployment patterns into templates with variables. The Ping Identity Helm chart includes Kubernetes templates and default values maintained by Ping Identity. With these in hand, you only need to provide values for the template variables to match your environment.
For example, a service definition looks like the following file. With this file, Kubernetes is instructed to create a
service resource with the name
apiVersion: v1 kind: Service metadata: labels: app.kubernetes.io/instance: myping app.kubernetes.io/name: pingdirectory name: myping-pingdirectory spec: ports: - name: https port: 443 protocol: TCP targetPort: 1443 - name: ldap port: 389 protocol: TCP targetPort: 1389 - name: ldaps port: 636 protocol: TCP targetPort: 1636 selector: app.kubernetes.io/instance: myping app.kubernetes.io/name: pingdirectory type: ClusterIP
Using our Helm chart, you can automatically define this entire resource and all other required resources for a basic deployment by setting
Manifests - the final Kubernetes YAML files that are sent to the cluster for resource creation. These files are standard Kubernetes files and will be similar to the service defined above.
Helm Templates - Go Template versions of Kubernetes YAML files. These templates enable the manifest creation to be paramaterized.
Values and values.yaml - A value is the setting you pass to a Helm chart from which the templates produce the manifests you want. Values can be passed individually on the command line, but more commonly they are collected and defined in a file named values.yaml. For example, if this file only had this entry, the resulting Kubernetes manifest file would be over 200 lines long.
pingdirectory: enabled: true
release - When you deploy resources with Helm, you provide a name for identification. The combination of this name and the resources deployed along with it make up a
release. When using Helm, it is a common pattern to prefix all resources managed by a release with the release name. In our examples,
myping is the release name, so you will see products in Kubernetes running with names similar to
Building the Helm Values File ¶
This documentation focuses on the Ping Identity DevOps Helm chart and the values passed to the Helm chart to achieve your configuration. For your deployment to fit your goals, you must create a values.yaml file.
The most simple values.yaml for our Helm chart would be:
global: enabled: true
By default, this flag is set as
global.enabled=false. These two lines are sufficient to turn on every available Ping Identity software product with a basic configuration.
Providing your own server profile ¶
In the documentation, therre is an example for providing your own server profile stored in GitHub to PingDirectory along with this snippet in the values.yaml specific to that feature:
pingdirectory: envs: SERVER_PROFILE_URL: https://github.com/<your-github-user>/pingidentity-server-profiles
This piece alone will not turn on PingDirectory, because the default value for
pingdirectory.enabled is false. To complete the deployment, add the snippet into your own values.yaml file:
global: enabled: true pingdirectory: envs: SERVER_PROFILE_URL: https://github.com/<your-github-user>/pingidentity-server-profiles
This example file turns on all products, including PingDirectory, and overwrites the default
pingdirectory.envs.SERVER_PROFILE_URL to use
This use of substitution and parameters is where the power of Helm to simplify ease of deployment begins to shine. To fully customize your deployment, review all available options by running:
helm show values pingidentity/ping-devops
This command prints all of the default values applied to your deployment. To overwrite any default values from the chart, copy the corresponding snippet, include and modify it in your own values.yaml file. Remember with YAML that tabbing and spacing matters. For most editors, copying all the way to the left margin and pasting at the very beginning of a line in your file should maintain proper indentation.
Helm also provides a wide variety of plugins. A useful one is Helm diff. This plugin shows what changes would be applied between Helm upgrade commands. For example, if this plugin indicates anything in a Deployment or Statefulset would change, you can expect the corresponding pods to be cycled. In this example, Helm diff is useful to note changes that would occur, particularly when you are not prepared for containers to be restarted.
Additional Commands ¶
As you go through the Helm examples, the goal is to build a values.yaml file that works in your environment.
Deploy a release: ¶
helm upgrade --install <release_name> pingidentity/ping-devops -f /path/to/values.yaml
Clean up a release: ¶
helm uninstall <release name>
Delete PVCs associated to a release: ¶
kubectl delete pvc --selector=app.kubernetes.io/instance=<release_name>
Exit Codes ¶
|Exit Code 0||Absence of an attached foreground process|
|Exit Code 1||Indicates failure due to application error|
|Exit Code 137||Indicates failure as container received SIGKILL (manual intervention or ‘oom-killer’ [OUT-OF-MEMORY])|
|Exit Code 139||Indicates failure as container received SIGSEGV|
|Exit Code 143||Indicates failure as a container received SIGTERM|
Example Configurations ¶
The following links contain example configurations and examples of how to run and configure Ping products using the Ping Devops Helm Chart. Please review the Getting Started Page before trying them.
|Everything||Example with most products integrated together||everything.yaml|
|PingFederate||PingFederate Admin Console & Engine||pingfederate.yaml|
|Simple Sync||PingDataSync and PingDirectory||simple-sync.yaml|