Java client for the kubernetes API.
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 will upgrade a major version, be prepared for potential breaking changes.
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.
Add this dependency to your project's POM:
<dependency>
<groupId>io.kubernetes</groupId>
<artifactId>client-java</artifactId>
<version>10.0.0</version>
</dependency>
compile 'io.kubernetes:client-java:10.0.0'
At first generate the JAR by executing:
git clone --recursive https://github.com/kubernetes-client/java
cd java/kubernetes
mvn package
Then manually install the following JARs:
- target/client-java-api-10.0.1-SNAPSHOT.jar
- target/lib/*.jar
1. Exception on deleting resources: "java.lang.IllegalStateException: Expected a string but was BEGIN_OBJECT..."
This is happening because openapi schema from kubernetes upstream doesn't match its implementation due to the limitation of openapi v2 schema expression #86. Consider either catch and ignore the JsonSyntaxException or do the deletion in the following form:
We prepared a few examples for common use-cases which are shown below:
- Configuration:
- InClusterClientExample: Configure a client while running inside the Kubernetes cluster.
- KubeConfigFileClientExample: Configure a client to access a Kubernetes cluster from outside.
- Basics:
- SimpleExample: Simple minimum example of how to use the client.
- ProtoExample: Request/receive payloads in protobuf serialization protocol.
- (5.0.0+) PatchExample:
Patch resource objects in various supported patch formats, equal to
kubectl patch
. - FluentExample: Construct arbitrary resource in a fluent builder style.
- YamlExample: Suggested way to load or dump resource in Yaml.
- Streaming:
- WatchExample:
Subscribe watch events from certain resources, equal to
kubectl get <resource> -w
. - LogsExample:
Fetch logs from running containers, equal to
kubectl logs
. - ExecExample:
Establish an "exec" session with running containers, equal to
kubectl exec
. - PortForwardExample:
Maps local port to a port on the pod, equal to
kubectl port-forward
. - AttachExample:
Attach to a process that is already running inside an existing container, equal to
kubectl attach
. - CopyExample:
Copy files and directories to and from containers, equal to
kubectl cp
. - WebSocketsExample: Establish an arbitrary web-socket session to certain resources.
- WatchExample:
Subscribe watch events from certain resources, equal to
- Advanced: (NOTE: The following example requires
client-java-extended
module)- (5.0.0+) InformerExample: Build an informer which list-watches resources and reflects the notifications to a local cache.
- (5.0.0+) PagerExample: Support Pagination (only for the list request) to ease server-side loads/network congestion.
- (6.0.0+) ControllerExample: Build a controller reconciling the state of world by list-watching one or multiple resources.
- (6.0.0+) LeaderElectionExample: Leader election utilities to help implement HA controllers.
- (9.0.0+) SpringIntegrationControllerExample: Building a kubernetes controller based on spring framework's bean injection.
- (9.0.0+) GenericKubernetesClientExample: Construct a generic client interface for any kubernetes types, including CRDs.
list all pods:
import io.kubernetes.client.openapi.ApiClient;
import io.kubernetes.client.openapi.ApiException;
import io.kubernetes.client.openapi.Configuration;
import io.kubernetes.client.openapi.apis.CoreV1Api;
import io.kubernetes.client.openapi.models.V1Pod;
import io.kubernetes.client.openapi.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.openapi.ApiClient;
import io.kubernetes.client.openapi.ApiException;
import io.kubernetes.client.openapi.Configuration;
import io.kubernetes.client.openapi.apis.CoreV1Api;
import io.kubernetes.client.openapi.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"
The project also provides model classes generated from some frequently used open source projects as separate maven dependencies. Please refer to the following to see their respective documentation.
All APIs and Models' documentation can be found at the Generated client's docs
client version | 1.13 | 1.14 | 1.15 | 1.16 | 1.17 | 1.18 |
---|---|---|---|---|---|---|
5.0.0 | ✓ | - | - | x | x | x |
6.0.1 | + | ✓ | - | - | x | x |
7.0.0 | + | + | ✓ | - | - | x |
8.0.2 | + | + | + | ✓ | - | - |
9.0.2 | + | + | + | + | ✓ | - |
10.0.0 | + | + | + | + | + | ✓ |
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).x
The Kubernetes cluster has no guarantees to support the API client of this version, as it only promises n-2 version support. It is not tested, and operations using API versions that have been deprecated and removed in later server versions won't function correctly.
See the CHANGELOG for a detailed description of changes between java-client versions.
Please see CONTRIBUTING.md for instructions on how to contribute.
Participation in the Kubernetes community is governed by the CNCF Code of Conduct.
The code is generated by the openapi-generator 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 and run the formatter:
cd ${HOME}/src/java
${GEN_ROOT}/gen/openapi/java.sh kubernetes ./settings
./mvnw spotless:apply
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.