Skip to content

Latest commit

 

History

History
806 lines (664 loc) · 28.3 KB

README.md

File metadata and controls

806 lines (664 loc) · 28.3 KB
Raw

Helm Client for Java

Run Helm commands directly from Java with this client library without the need for a Helm CLI.

It allows you to execute Helm commands directly from Java without requiring a separate Helm installation. Despite this, it still leverages the native Helm libraries, which are written in Go, to function. As a result, you can expect the same behavior as you would get from using Helm directly.

Getting started

Add the dependency to your project:

<dependency>
  <groupId>com.marcnuri.helm-java</groupId>
  <artifactId>helm-java</artifactId>
  <version>0.0.12</version>
</dependency>

Start using it:

public static void main(String... args) {
  new Helm(Paths.get("path", "to", "chart")).install().call();
}

Check the features section for more examples and documentation.

Features

Create

Equivalent of helm create.

Creates a chart directory along with the common files and directories used in a chart.

Helm.create()
  // Name of the chart to create
  .withName("test")
  // Path to the directory where the new chart directory will be created
  .withDir(Paths.get("/tmp"))
  .call();

Dependency

Equivalent of helm dependency.

Manage a chart's dependencies.

Dependency build

Equivalent of helm dependency build.

Rebuild the chart's on-disk dependencies (charts/) based on the Chart.lock file.

new Helm(Paths.get("path", "to", "chart")).dependency().build()
  // Optionally specify a keyring containing public keys (used for verification)
  .keyring(Paths.get("path", "to", "keyring"))
  // Optionally skip refreshing the local repository cache
  .skipRefresh()
  // Optionally verify the packages against signatures
  .verify()
  // Optionally enable verbose output
  .debug()
  .call();

Dependency list

Equivalent of helm dependency list.

List the dependencies for the given chart.

new Helm(Paths.get("path", "to", "chart")).dependency().list()
  .getDependencies();

Dependency update

Equivalent of helm dependency update.

Update chart's on-disk dependencies (charts/) to mirror the contents of Chart.yaml.

new Helm(Paths.get("path", "to", "chart")).dependency().update()
  // Optionally specify a keyring containing public keys (used for verification)
  .keyring(Paths.get("path", "to", "keyring"))
  // Optionally skip refreshing the local repository cache
  .skipRefresh()
  // Optionally verify the packages against signatures
  .verify()
  // Optionally enable verbose output
  .debug()
  .call();

Install

Equivalent of helm install.

Installs a chart archive.

// Instantiate the command with chart reference
InstallCommand installCommand = Helm.install("chart/reference");
// Instatiate the command with chart archive
InstallCommand installCommand = new Helm(Paths.get("path", "to", "chart")).install();
Release result = installCommand
  // Name of the release to install
  .withName("release-name")
  // Optionally generate a release name (and omit the name parameter)
  .generateName()
  // Optionally specify a template for the name generation
  .withNameTemplate("a-chart-{{randAlpha 6 | lower}}")
  // Optionally specify a version constraint for the chart version to use.
  .withVersion("^1.0.0")
  // Optionally specify the Kubernetes namespace to install the release into
  .withNamespace("namespace")
  // Optionally create the namespace if not present
  .createNamespace()
  // Optionally, if set, the installation process deletes the installation on failure
  .atomic()
  // Optionally specify a custom description for the release
  .withDescription("the-description")
  // Optionally enable the use of development versions too
  .devel()
  // Optionally update dependencies if they are missing before installing the chart
  .dependencyUpdate()
  // Optionally disable the validation of rendered templates against the Kubernetes OpenAPI Schema
  .disableOpenApiValidation()
  // Optionally enable dry run mode to simulate an install
  .dryRun()
  // Optionally specify the dry run strategy (client, server, or none). If unset, defaults to client
  .withDryRunOption(DryRun.CLIENT)
  // Optionally wait until all Pods are in a ready state, PVCs are bound, Deployments have
  // minimum (Desired minus maxUnavailable) Pods in ready state and Services have an IP
  // address (and Ingress if a LoadBalancer) before marking the release as successful. 
  .waitReady()
  // Optionally set typed values for the chart (can be repeated)
  .set("key", "value")
  // Optionally specify the path to the kubeconfig file to use for CLI requests
  .withKubeConfig(Paths.get("path", "to", "kubeconfig"))
  // Optionally specify an SSL certificate file to identify the registry client
  .withCertFile(Paths.get("path", "to", "cert"))
  // Optionally specify an SSL key file to identify the registry client
  .withKey(Paths.get("path", "to", "key"))
  // Optionally verify certificates of HTTPS-enabled servers using this CA bundle
  .withCaFile(Paths.get("path", "to", "ca"))
  // Optionally skip TLS certificate checks of HTTPS-enabled servers
  .insecureSkipTlsVerify()
  // Optionally allow insecure plain HTTP connections for the chart download
  .plainHttp()
  // Optionally specify a keyring (used for verification)
  .withKeyring(Paths.get("path", "to", "keyring"))
  // Optionally enable verbose output
  .debug()
  // Optionally set the path to the file containing repository names and URLs
  // Defaults to "~/.config/helm/repositories.yaml"
  .withRepositoryConfig(Paths.get("path", "to", "config"))
  .call();

Lint

Equivalent of helm lint.

Examine a chart for possible issues.

LintResult result = new Helm(Paths.get("path", "to", "chart")).lint()
  // Optionally enable strict mode (fail on lint warnings)
  .strict()
  // Optionally enable quiet mode (only show warnings and errors) 
  .quiet()
  .call();
result.isFailed(); // true if linting failed
result.getMessages(); // list of linting messages

List

Equivalent of helm list.

Lists all the releases for a specified namespace (uses current namespace context if namespace not specified).

List<Release> releases = Helm.list()
  // Optionally specify the Kubernetes namespace to list the releases from
  .withNamespace("namespace")
  // Optionally specify the path to the kubeconfig file to use for CLI requests
  .withKubeConfig(Paths.get("path", "to", "kubeconfig"))
  // Optionally show all releases without any filter applied
  .all()
  // Optionally show releases across all namespaces
  .allNamespaces()
  // Optionally show deployed releases
  // If no other option is specified, this will be automatically enabled
  .deployed()
  // Optionally show failed releases
  .failed()
  // Optionally show pending releases
  .pending()
  // Optionally show superseded releases
  .superseded()
  // Optionally show uninstalled releases (if 'helm uninstall --keep-history' was used)
  .uninstalled()
  // Optionally show releases that are currently being uninstalled
  .uninstalling()
  .call();

Package

Equivalent of helm package.

Package a chart directory into a chart archive.

Path result = new Helm(Paths.get("path", "to", "chart")).package()
  // Optionally specify a target directory
  .destination(Paths.get("path", "to", "destination"))
  // Optionally enable signing
  .sign()
  // Optionally specify a key UID (required if signing)
  .withKey("KEY_UID")
  // Optionally specify a keyring (required if signing)
  .withKeyring(Paths.get("path", "to", "keyring"))
  // Optionally specify a file containing the passphrase for the signing key
  .withPassphraseFile(Paths.get("path", "to", "passphrase"))
  .call();

Push

Equivalent of helm push.

Upload a chart to a registry.

Helm.push()
  // Location of the packaged chart (.tgz) to push
  .withChart(Paths.get("path", "to", "chart", "package"))
  // URI of the remote registry to push the chart to
  .withRemote("oci://remote-server.example.com:12345");
  // Optionally specify an SSL certificate file to identify the registry client
  .withCertFile(Paths.get("path", "to", "cert"))
  // Optionally specify an SSL key file to identify the registry client
  .withKey(Paths.get("path", "to", "key"))
  // Optionally specify an SSL CA bundle file to verify the HTTPS-enabled registry server certificates
  .withCaFile(Paths.get("path", "to", "ca"))
  // Optionally skip TLS certificate checks of HTTPS-enabled servers
  .insecureSkipTlsVerify()
  // Optionally use insecure HTTP connections for the chart upload
  .plainHttp()
  // Optionally enable debug mode to print out verbose information
  .debug()
  .call();

Registry

Equivalent of helm registry.

Log in to or log out from a registry.

Registry login

Equivalent of helm registry login.

Log in to a registry.

Helm.registry().login()
  // The host to log in to.
  .withHost("host")
  // Registry username
  .withUsername("username");
  // Registry password or identity token.
  .withPassword("password");
  // Optionally specify an SSL certificate file to identify the registry client
  .withCertFile(Paths.get("path", "to", "cert"))
  // Optionally specify an SSL key file to identify the registry client
  .withKey(Paths.get("path", "to", "key"))
  // Optionally specify an SSL CA bundle file to verify the HTTPS-enabled registry server certificates
  .withCaFile(Paths.get("path", "to", "ca"))
  // Optionally skip TLS certificate checks of HTTPS-enabled servers
  .insecureSkipTlsVerify()
  // Optionally use insecure HTTP connections for the chart upload
  .plainHttp()
  // Optionally enable debug mode to print out verbose information
  .debug()
  .call();

Registry logout

Equivalent of helm registry logout.

Log out from a registry.

Helm.registry().logout()
  // The host to log out from.
  .withHost("host")
  // Optionally enable debug mode to print out verbose information
  .debug()
  .call();

Repo

Equivalent of helm repo.

Add, list, remove, update, and index chart repositories.

Repo add

Equivalent of helm repo add.

Add a chart repository.

Helm.repo().add()
  // Optionally set the path to the file containing repository names and URLs
  // Defaults to "~/.config/helm/repositories.yaml"
  .withRepositoryConfig(Paths.get("path", "to", "config"))
  // Name of the repository to add
  .withName("repo-1")
  // URL of the repository to add
  .withUrl(URI.create("https://charts.helm.sh/stable"))
  // Optionally specify a username for HTTP basic authentication
  .withUsername("user")
  // Optionally specify a password for HTTP basic authentication
  .withPassword("pass")
  // Optionally specify an SSL certificate file to identify the HTTPS client
  .withCertFile(Paths.get("path", "to", "cert"))
  // Optionally specify an SSL key file to identify the HTTPS client
  .withKey(Paths.get("path", "to", "key"))
  // Optionally verify certificates of HTTPS-enabled servers using this CA bundle
  .withCaFile(Paths.get("path", "to", "ca"))
  // Optionally skip TLS certificate checks of HTTPS-enabled servers
  .insecureSkipTlsVerify()
  .call()

Repo list

Equivalent of helm repo list.

List chart repositories.

List<Repository> respositories = Helm.repo().list()
  // Optionally set the path to the file containing repository names and URLs
  // Defaults to "~/.config/helm/repositories.yaml"
  .withRepositoryConfig(Paths.get("path", "to", "config"))
  .call();

Repo remove

Equivalent of helm repo remove.

Remove one or more chart repositories.

Helm.repo().remove()
  // Optionally set the path to the file containing repository names and URLs
  // Defaults to "~/.config/helm/repositories.yaml"
  .withRepositoryConfig(Paths.get("path", "to", "config"))
  // Add a repository name to the list of repos to remove
  .withRepo("repo-1")
  // Add another repository name to the list of repos to remove
  .withRepo("repo-2")
  .call();

Repo update

Equivalent of helm repo update.

Update information of available charts locally from chart repositories.

Helm.repo().update()
  // Optionally set the path to the file containing repository names and URLs
  // Defaults to "~/.config/helm/repositories.yaml"
  .withRepositoryConfig(Paths.get("path", "to", "config"))
  // Add a repository name to the list of repos to remove
  .withRepo("repo-1")
  // Add another repository name to the list of repos to remove
  .withRepo("repo-2")
  .call();

Search

Equivalent of helm search.

This command provides the ability to search for Helm charts in various places including the Artifact Hub and the repositories you have added.

Repo

Equivalent of helm search repo.

Search repositories for a keyword in charts.

List<SearchResult> results = Helm.search().repo()
  // Optionally set the path to the file containing repository names and URLs
  // Defaults to "~/.config/helm/repositories.yaml"
  .withRepositoryConfig(Paths.get("path", "to", "config"))
  // Optionally set the keyword to match against the repo name, chart name, chart keywords, and description.
  .withKeyword("keyword")
  // Optionally use regular expressions for searching.
  .regexp()
  // Optionally search for development versions too (alpha, beta, and release candidate releases).
  .devel()
  // Optionally search using semantic versioning constraints
  .withVersion(">=1.0.0")
  .call();

Show

Equivalent of helm show.

Show information about a chart.

Show all

Equivalent of helm show all.

Show all information about a chart.

// Instantiate the command with chart reference
ShowCommand showCommand = Helm.show("chart/reference");
// Instatiate the command with chart archive
ShowCommand showCommand = new Helm(Paths.get("path", "to", "chart")).show();
String result = showCommand.all()
  // Optionally specify a version constraint for the chart version to use.
  .withVersion("^1.0.0")
  // Optionally specify an SSL certificate file to identify the registry client
  .withCertFile(Paths.get("path", "to", "cert"))
  // Optionally specify an SSL key file to identify the registry client
  .withKey(Paths.get("path", "to", "key"))
  // Optionally specify an SSL CA bundle file to verify the HTTPS-enabled registry server certificates
  .withCaFile(Paths.get("path", "to", "ca"))
  // Optionally skip TLS certificate checks of HTTPS-enabled servers
  .insecureSkipTlsVerify()
  // Optionally use insecure HTTP connections for the chart upload
  .plainHttp()
  // Optionally enable debug mode to print out verbose information
  .debug()
  .call();

Show chart

Equivalent of helm show chart.

Show the chart's definition.

String result = new Helm(Paths.get("path", "to", "chart")).show()
  .chart()
  // Optionally specify a version constraint for the chart version to use.
  .withVersion("^1.0.0")
  // Optionally specify an SSL certificate file to identify the registry client
  .withCertFile(Paths.get("path", "to", "cert"))
  // Optionally specify an SSL key file to identify the registry client
  .withKey(Paths.get("path", "to", "key"))
  // Optionally specify an SSL CA bundle file to verify the HTTPS-enabled registry server certificates
  .withCaFile(Paths.get("path", "to", "ca"))
  // Optionally skip TLS certificate checks of HTTPS-enabled servers
  .insecureSkipTlsVerify()
  // Optionally use insecure HTTP connections for the chart upload
  .plainHttp()
  // Optionally enable debug mode to print out verbose information
  .debug()
  .call();

Show CRDs

Equivalent of helm show crds.

Show the chart's CRDs.

String result = new Helm(Paths.get("path", "to", "chart")).show()
  .crds()
  // Optionally specify a version constraint for the chart version to use.
  .withVersion("^1.0.0")
  // Optionally specify an SSL certificate file to identify the registry client
  .withCertFile(Paths.get("path", "to", "cert"))
  // Optionally specify an SSL key file to identify the registry client
  .withKey(Paths.get("path", "to", "key"))
  // Optionally specify an SSL CA bundle file to verify the HTTPS-enabled registry server certificates
  .withCaFile(Paths.get("path", "to", "ca"))
  // Optionally skip TLS certificate checks of HTTPS-enabled servers
  .insecureSkipTlsVerify()
  // Optionally use insecure HTTP connections for the chart upload
  .plainHttp()
  // Optionally enable debug mode to print out verbose information
  .debug()
  .call();

Show README

Equivalent of helm show readme.

Show the chart's README.

String result = new Helm(Paths.get("path", "to", "chart")).show()
  .readme()
  // Optionally specify a version constraint for the chart version to use.
  .withVersion("^1.0.0")
  // Optionally specify an SSL certificate file to identify the registry client
  .withCertFile(Paths.get("path", "to", "cert"))
  // Optionally specify an SSL key file to identify the registry client
  .withKey(Paths.get("path", "to", "key"))
  // Optionally specify an SSL CA bundle file to verify the HTTPS-enabled registry server certificates
  .withCaFile(Paths.get("path", "to", "ca"))
  // Optionally skip TLS certificate checks of HTTPS-enabled servers
  .insecureSkipTlsVerify()
  // Optionally use insecure HTTP connections for the chart upload
  .plainHttp()
  // Optionally enable debug mode to print out verbose information
  .debug()
  .call();

Show values

Equivalent of helm show values.

Show the chart's values.

String result = new Helm(Paths.get("path", "to", "chart")).show()
  .values()
  // Optionally specify a version constraint for the chart version to use.
  .withVersion("^1.0.0")
  // Optionally specify an SSL certificate file to identify the registry client
  .withCertFile(Paths.get("path", "to", "cert"))
  // Optionally specify an SSL key file to identify the registry client
  .withKey(Paths.get("path", "to", "key"))
  // Optionally specify an SSL CA bundle file to verify the HTTPS-enabled registry server certificates
  .withCaFile(Paths.get("path", "to", "ca"))
  // Optionally skip TLS certificate checks of HTTPS-enabled servers
  .insecureSkipTlsVerify()
  // Optionally use insecure HTTP connections for the chart upload
  .plainHttp()
  // Optionally enable debug mode to print out verbose information
  .debug()
  .call();

Template

Equivalent of helm template.

This command renders chart templates locally and displays the output.

// Instantiate the command with chart reference
TemplateCommand templateCommand = Helm.template("chart/reference");
// Instatiate the command with chart archive
TemplateCommand templateCommand = new Helm(Paths.get("path", "to", "chart")).template();
String result = templateCommand
  // Optionally specify a name for the release
  .withName("release-name")
  // Optionally specify a version constraint for the chart version to use.
  .withVersion("^1.0.0")
  // Optionally specify the Kubernetes namespace for the release
  .withNamespace("namespace")
  // Optionally update dependencies if they are missing before installing the chart
  .dependencyUpdate()
  // Optionally set values for the chart
  .set("key", "value")
  // Optionally specify an SSL certificate file to identify the registry client
  .withCertFile(Paths.get("path", "to", "cert"))
  // Optionally specify an SSL key file to identify the registry client
  .withKey(Paths.get("path", "to", "key"))
  // Optionally verify certificates of HTTPS-enabled servers using this CA bundle
  .withCaFile(Paths.get("path", "to", "ca"))
  // Optionally skip TLS certificate checks of HTTPS-enabled servers
  .insecureSkipTlsVerify()
  // Optionally allow insecure plain HTTP connections for the chart download
  .plainHttp()
  // Optionally specify a keyring (used for verification)
  .withKeyring(Paths.get("path", "to", "keyring"))
  // Optionally enable debug mode to print out verbose information
  .debug()
  // Optionally set the path to the file containing repository names and URLs
  // Defaults to "~/.config/helm/repositories.yaml"
  .withRepositoryConfig(Paths.get("path", "to", "config"))
  .call();

Test

Equivalent of helm test.

This command runs the tests for a release.

Release result = Helm.test("chart/reference")
  // Optionally specify the time (in seconds) to wait for any individual Kubernetes operation (like Jobs for hooks) (default 300)
  .withTimeout(int timeout)
  // Optionally specify the Kubernetes namespace
  .withNamespace("namespace")
  // Optionally specify the path to the kubeconfig file to use for CLI requests
  .withKubeConfig(Paths.get("path", "to", "kubeconfig"))
  // Optionally enable verbose output
  .debug()
  .call();

Uninstall

Equivalent of helm uninstall.

This command takes a release name and uninstalls the release.

String result = Helm.uninstall("chart/reference")
  // Optionally enable dry run mode to simulate an uninstall
  .dryRun()
  // Optionally prevent hooks from running during uninstallation
  .noHooks()
  // Optionally treat "release not found" as a successful uninstall
  .ignoreNotFound()
  // Optionally remove all associated resources and mark the release as deleted, but retain the release history
  .keepHistory()
  // Optionally select the deletion cascading strategy for the dependents. If unset, defaults to background
  .withCascade(Cascade.BACKGROUND)
  // Optionally specify the Kubernetes namespace to uninstall the release from
  .withNamespace("namespace")
  // Optionally specify the path to the kubeconfig file to use for CLI requests
  .withKubeConfig(Paths.get("path", "to", "kubeconfig"))
  // Optionally enable verbose output
  .debug()
  .call();

Upgrade

Equivalent of helm upgrade.

Upgrades a release to a new version of a chart.

// Instantiate the command with chart reference
UpgradeCommand upgradeCommand = Helm.upgrade("chart/reference");
// Instatiate the command with chart archive
UpgradeCommand upgradeCommand = new Helm(Paths.get("path", "to", "chart")).upgrade();
Release result = upgradeCommand
  // Name of the release to upgrade
  .withName("release-name")
  // Optionally specify a version constraint for the chart version to use.
  .withVersion("^1.0.0")
  // Optionally specify the Kubernetes namespace to upgrade the release
  .withNamespace("namespace")
  // Optionally run an installation if a release by this name doesn't already exist
  .install()
  // Optionally force resource updates through a replacement strategy
  .force()
  // Optionally reset the values to the ones built into the chart when upgrading
  .resetValues()
  // Optionally reuse the last release's values and merge in any overrides from the current values when upgrading
  // Ignored if used in combination with resetValues()
  .reuseValues()
  // Optionally reset the values to the ones built into the chart,
  // apply the last release's values and merge in any overrides from the current values when upgrading
  // Ignored if used in combination with resetValues() or reuseValues()
  .resetThenReuseValues()
  // Optionally, if set, upgrade process rolls back changes made in case of failed upgrade
  .atomic()
  // Optionally allow deletion of new resources created in this upgrade when upgrade fails
  .cleanupOnFail()
  // Optionally create the release namespace if not present (if install() is set)
  .createNamespace()
  // Optionally specify a custom description
  .withDescription("the-description")
  // Optionally enable the use of development versions too
  .devel()
  // Optionally update dependencies if they are missing before installing the chart
  .dependencyUpdate()
  // Optionally disable the validation of rendered templates against the Kubernetes OpenAPI Schema
  .disableOpenApiValidation()
  // Optionally enable dry run mode to simulate an install
  .dryRun()
  // Optionally specify the dry run strategy (client, server, or none). If unset, defaults to client
  .withDryRunOption(DryRun.CLIENT)
  // Optionally wait until all Pods are in a ready state, PVCs are bound, Deployments have
  // minimum (Desired minus maxUnavailable) Pods in ready state and Services have an IP
  // address (and Ingress if a LoadBalancer) before marking the release as successful. 
  .waitReady()
  // Optionally set typed values for the chart (can be repeated)
  .set("key", "value")
  // Optionally specify the path to the kubeconfig file to use for CLI requests
  .withKubeConfig(Paths.get("path", "to", "kubeconfig"))
  // Optionally specify an SSL certificate file to identify the registry client
  .withCertFile(Paths.get("path", "to", "cert"))
  // Optionally specify an SSL key file to identify the registry client
  .withKey(Paths.get("path", "to", "key"))
  // Optionally verify certificates of HTTPS-enabled servers using this CA bundle
  .withCaFile(Paths.get("path", "to", "ca"))
  // Optionally skip TLS certificate checks of HTTPS-enabled servers
  .insecureSkipTlsVerify()
  // Optionally allow insecure plain HTTP connections for the chart download
  .plainHttp()
  // Optionally specify a keyring (used for verification)
  .withKeyring(Paths.get("path", "to", "keyring"))
  // Optionally enable verbose output
  .debug()
  // Optionally set the path to the file containing repository names and URLs
  // Defaults to "~/.config/helm/repositories.yaml"
  .withRepositoryConfig(Paths.get("path", "to", "config"))
  .call();

Version

Similar to helm version.

Returns the version of the underlying Helm library.

String version = Helm.version();

Development

Project Structure

  • Go:
    • native: contains the Go project that creates the native c bindings
  • Java:
    • helm-java: contains the actual Helm Java client library
    • lib: contains the Java modules related to the native c binding libraries
      • api: contains the API for the native interfaces
      • darwin-amd64: contains the Java native access library for darwin/amd64
      • darwin-arm64: contains the Java native access library for darwin/arm64
      • linux-amd64: contains the Java native access library for linux/amd64
      • linux-arm64: contains the Java native access library for linux/arm64
      • windows-amd64: contains the Java native access library for windows/amd64

Release Process

Release to Maven Central

To release a new version automatically:

make release V=X.Y.Z VS=X.Y
  • V: New version to release.
  • VS: New SNAPSHOT version for Maven.

To release a new version manually:

  1. Update the version in the pom.xml file. 
    mvn versions:set -DnewVersion=X.Y.Z -DgenerateBackupPoms=false
  2. Commit and tag the release with the pom.xml version. 
    git add .
git commit -m "[RELEASE] vX.Y.Z released"
git tag vX.Y.Z
git push origin vX.Y.Z
  3. Update the version in the pom.xml file to the next snapshot version. 
    mvn versions:set -DnewVersion=X.Y-SNAPSHOT -DgenerateBackupPoms=false
  4. Commit the changes with the following message: 
    git add .
git commit -m "[RELEASE] v0.0.11 released, prepare for next development iteration"
git push origin master

Create GitHub Release

Once the release is published to Maven Central, create a new GitHub release for the released tag.

License Headers

Whenever a new file is created, the license header must be added. To add the license header to all files:

make license