Kubernetes Java Client

Java client for the kubernetes API.

Client versioning

The Java client uses Semantic Versioning. We increment the major version number whenever we regenerate the client for a new Kubernetes release version (see table below). Whenever we do this there are new APIs added and possibly breaking changes in the generated Kubernetes API Stubs. Whenever you upgrade a major version, be prepared for potential breaking changes.

Installation

To install the Java client library to your local Maven repository, simply execute:

git clone --recursive https://github.com/kubernetes-client/java
cd java
mvn install

Refer to the official documentation for more information.

Maven users

Add this dependency to your project's POM:

<dependency>
    <groupId>io.kubernetes</groupId>
    <artifactId>client-java</artifactId>
    <version>4.0.0</version>
    <scope>compile</scope>
</dependency>

Gradle users

compile 'io.kubernetes:client-java:4.0.0'

Others

At first generate the JAR by executing:

git clone --recursive https://github.com/kubernetes-client/java
cd java
cd kubernetes
mvn package

Then manually install the following JARs:

target/client-java-api-4.0.0-beta1-SNAPSHOT.jar
target/lib/*.jar

Example

list all pods:

import io.kubernetes.client.ApiClient;
import io.kubernetes.client.ApiException;
import io.kubernetes.client.Configuration;
import io.kubernetes.client.apis.CoreV1Api;
import io.kubernetes.client.models.V1Pod;
import io.kubernetes.client.models.V1PodList;
import io.kubernetes.client.util.Config;

import java.io.IOException;

public class Example {
    public static void main(String[] args) throws IOException, ApiException{
        ApiClient client = Config.defaultClient();
        Configuration.setDefaultApiClient(client);

        CoreV1Api api = new CoreV1Api();
        V1PodList list = api.listPodForAllNamespaces(null, null, null, null, null, null, null, null, null);
        for (V1Pod item : list.getItems()) {
            System.out.println(item.getMetadata().getName());
        }
    }
}

watch on namespace object:

import com.google.gson.reflect.TypeToken;
import io.kubernetes.client.ApiClient;
import io.kubernetes.client.ApiException;
import io.kubernetes.client.Configuration;
import io.kubernetes.client.apis.CoreV1Api;
import io.kubernetes.client.models.V1Namespace;
import io.kubernetes.client.util.Config;
import io.kubernetes.client.util.Watch;

import java.io.IOException;

public class WatchExample {
    public static void main(String[] args) throws IOException, ApiException{
        ApiClient client = Config.defaultClient();
        Configuration.setDefaultApiClient(client);

        CoreV1Api api = new CoreV1Api();

        Watch<V1Namespace> watch = Watch.createWatch(
                client,
                api.listNamespaceCall(null, null, null, null, null, 5, null, null, Boolean.TRUE, null, null),
                new TypeToken<Watch.Response<V1Namespace>>(){}.getType());

        for (Watch.Response<V1Namespace> item : watch) {
            System.out.printf("%s : %s%n", item.type, item.object.getMetadata().getName());
        }
    }
}

More examples can be found in examples folder. To run examples, run this command:

mvn exec:java -Dexec.mainClass="io.kubernetes.client.examples.Example"

Documentation

All APIs and Models' documentation can be found at the Generated client's docs

Compatibility

client version	1.9	1.10	1.11	1.12	1.13	1.14
2.0.0	✓	-	-	-	-	-
3.0.0	+	-	✓	-	-	-
4.0.0	+	+	+	✓	-	-
5.0.0	+	+	+	+	✓	-
6.0.0-beta1	+	+	+	+	+	✓

Key:

✓ Exactly the same features / API objects in both java-client and the Kubernetes version.
+ java-client has features or api objects that may not be present in the Kubernetes cluster, but everything they have in common will work.
- The Kubernetes cluster has features the java-client library can't use (additional API objects, etc).

See the CHANGELOG for a detailed description of changes between java-client versions.

Contributing

Please see CONTRIBUTING.md for instructions on how to contribute.

Code of Conduct

Participation in the Kubernetes community is governed by the CNCF Code of Conduct.

Development

Update the generated code.

The code is generated by the swagger-codegen project.

We have built general purpose cross-language tools for generating code, it is hosted in the kubernetes-client/gen repository.

To get started, in a root directory that is not your java client directory, for example your directory layout could be:

${HOME}/
        src/
             gen/
             java/
...

Then to clone the gen repository, you would run:

cd ${HOME}/src
git clone https://github.com/kubernetes-client/gen
export GEN_ROOT=${PWD}

Then to update the client:

cd ${HOME}/src/java
${GEN_ROOT}/gen/openapi/java.sh kubernetes ./settings

This should run through a long-ish build process involving docker and eventually result in a new set of generated code in the kubernetes directory.

junbeomlee / java