Keywords
License
- Apache-2.0
- Yesattribution
- Permissivelinking
- Permissivedistribution
- Permissivemodification
- Yespatent grant
- Yesprivate use
- Permissivesublicensing
- Notrademark grant
Readme
Kubernetes & OpenShift Java Client
This client provides access to the full Kubernetes & OpenShift REST APIs via a fluent DSL.
Module Maven Central Javadoc kubernetes-client openshift-client Extensions Maven Central Javadoc knative-client tekton-client chaosmesh-client volumesnapshot-client volcano-client istio-client open-cluster-management-client
Contents
- Usage
- Creating a client
- Configuring the client
- Loading resources from external sources
- Passing a reference of a resource to the client
- Adapting a client
- Adapting and close
- Generating CRD from Java
- Generating Java from CRD
- Mocking Kubernetes
- Who Uses Fabric8 Kubernetes Client?
- Kubernetes Operators in Java Written using Fabric8 Kubernetes Client
- Kubernetes and Red Hat OpenShift Compatibility
- Kubernetes Client CHEAT SHEET
- Kubectl Java Equivalents
- FAQs - which includes details about project dependencies.
Usage
Creating a client
The easiest way to create a client is:
KubernetesClient client = new KubernetesClientBuilder().build();
DefaultOpenShiftClient
implements both the KubernetesClient
& OpenShiftClient
interface so if you need the
OpenShift extensions, such as Build
s, etc then simply do:
OpenShiftClient osClient = new KubernetesClientBuilder().build().adapt(OpenShiftClient.class);
Configuring the client
This will use settings from different sources in the following order of priority:
- System properties
- Environment variables
- Kube config file
- Service account token & mounted CA certificate
System properties are preferred over environment variables. The following system properties & environment variables can be used for configuration:
Property / Environment Variable Description Default valuekubernetes.disable.autoConfig
/ KUBERNETES_DISABLE_AUTOCONFIG
Disable automatic configuration (KubernetesClient would not look in ~/.kube/config
, mounted ServiceAccount, environment variables or System properties for Kubernetes cluster information)
false
kubernetes.master
/ KUBERNETES_MASTER
Kubernetes master URL
https://kubernetes.default.svc
kubernetes.api.version
/ KUBERNETES_API_VERSION
API version
v1
openshift.url
/ OPENSHIFT_URL
OpenShift master URL
Kubernetes master URL value
kubernetes.oapi.version
/ KUBERNETES_OAPI_VERSION
OpenShift API version
v1
kubernetes.trust.certificates
/ KUBERNETES_TRUST_CERTIFICATES
Trust all certificates
false
kubernetes.disable.hostname.verification
/ KUBERNETES_DISABLE_HOSTNAME_VERIFICATION
false
kubernetes.certs.ca.file
/ KUBERNETES_CERTS_CA_FILE
kubernetes.certs.ca.data
/ KUBERNETES_CERTS_CA_DATA
kubernetes.certs.client.file
/ KUBERNETES_CERTS_CLIENT_FILE
kubernetes.certs.client.data
/ KUBERNETES_CERTS_CLIENT_DATA
kubernetes.certs.client.key.file
/ KUBERNETES_CERTS_CLIENT_KEY_FILE
kubernetes.certs.client.key.data
/ KUBERNETES_CERTS_CLIENT_KEY_DATA
kubernetes.certs.client.key.algo
/ KUBERNETES_CERTS_CLIENT_KEY_ALGO
Client key encryption algorithm
RSA
kubernetes.certs.client.key.passphrase
/ KUBERNETES_CERTS_CLIENT_KEY_PASSPHRASE
kubernetes.auth.basic.username
/ KUBERNETES_AUTH_BASIC_USERNAME
kubernetes.auth.basic.password
/ KUBERNETES_AUTH_BASIC_PASSWORD
kubernetes.auth.serviceAccount.token
/ KUBERNETES_AUTH_SERVICEACCOUNT_TOKEN
Name of the service account token file
/var/run/secrets/kubernetes.io/serviceaccount/token
kubernetes.auth.tryKubeConfig
/ KUBERNETES_AUTH_TRYKUBECONFIG
Configure client using Kubernetes config
true
kubeconfig
/ KUBECONFIG
Name of the kubernetes config file to read
~/.kube/config
kubernetes.auth.tryServiceAccount
/ KUBERNETES_AUTH_TRYSERVICEACCOUNT
Configure client from Service account
true
kubernetes.tryNamespacePath
/ KUBERNETES_TRYNAMESPACEPATH
Configure client namespace from Kubernetes service account namespace path
true
kubernetes.auth.token
/ KUBERNETES_AUTH_TOKEN
kubernetes.watch.reconnectInterval
/ KUBERNETES_WATCH_RECONNECTINTERVAL
Watch reconnect interval in ms
1000
kubernetes.watch.reconnectLimit
/ KUBERNETES_WATCH_RECONNECTLIMIT
Number of reconnect attempts (-1 for infinite)
-1
kubernetes.connection.timeout
/ KUBERNETES_CONNECTION_TIMEOUT
Connection timeout in ms (0 for no timeout)
10000
kubernetes.request.timeout
/ KUBERNETES_REQUEST_TIMEOUT
Read timeout in ms
10000
kubernetes.upload.connection.timeout
/ KUBERNETES_UPLOAD_CONNECTION_TIMEOUT
Pod upload connection timeout in ms
10000
kubernetes.upload.request.timeout
/ KUBERNETES_UPLOAD_REQUEST_TIMEOUT
Pod upload request timeout in ms
120000
kubernetes.request.retry.backoffLimit
/ KUBERNETES_REQUEST_RETRY_BACKOFFLIMIT
Number of retry attempts (-1 for infinite)
10
kubernetes.request.retry.backoffInterval
/ KUBERNETES_REQUEST_RETRY_BACKOFFINTERVAL
Retry initial backoff interval in ms
100
kubernetes.rolling.timeout
/ KUBERNETES_ROLLING_TIMEOUT
Rolling timeout in ms
900000
kubernetes.logging.interval
/ KUBERNETES_LOGGING_INTERVAL
Logging interval in ms
20000
kubernetes.scale.timeout
/ KUBERNETES_SCALE_TIMEOUT
Scale timeout in ms
600000
kubernetes.websocket.timeout
/ KUBERNETES_WEBSOCKET_TIMEOUT
Websocket timeout in ms
5000
kubernetes.websocket.ping.interval
/ KUBERNETES_WEBSOCKET_PING_INTERVAL
Websocket ping interval in ms
30000
kubernetes.max.concurrent.requests
/ KUBERNETES_MAX_CONCURRENT_REQUESTS
64
kubernetes.max.concurrent.requests.per.host
/ KUBERNETES_MAX_CONCURRENT_REQUESTS_PER_HOST
5
kubernetes.impersonate.username
/ KUBERNETES_IMPERSONATE_USERNAME
Impersonate-User
HTTP header value
kubernetes.impersonate.group
/ KUBERNETES_IMPERSONATE_GROUP
Impersonate-Group
HTTP header value
kubernetes.tls.versions
/ KUBERNETES_TLS_VERSIONS
TLS versions separated by ,
TLSv1.2,TLSv1.3
kubernetes.truststore.file
/ KUBERNETES_TRUSTSTORE_FILE
kubernetes.truststore.passphrase
/ KUBERNETES_TRUSTSTORE_PASSPHRASE
kubernetes.keystore.file
/ KUBERNETES_KEYSTORE_FILE
kubernetes.keystore.passphrase
/ KUBERNETES_KEYSTORE_PASSPHRASE
kubernetes.backwardsCompatibilityInterceptor.disable
/ KUBERNETES_BACKWARDSCOMPATIBILITYINTERCEPTOR_DISABLE
Disable the BackwardsCompatibilityInterceptor
true
no.proxy
/ NO_PROXY
comma-separated list of domain extensions proxy should not be used for
http.proxy
/ HTTP_PROXY
URL to the proxy for HTTP requests (See Proxy precedence)
https.proxy
/ HTTPS_PROXY
URL to the proxy for HTTPS requests (See Proxy precedence)
Alternatively you can use the ConfigBuilder
to create a config object for the Kubernetes client:
Config config = new ConfigBuilder().withMasterUrl("https://mymaster.com").build();
KubernetesClient client = new KubernetesClientBuilder().withConfig(config).build();
Using the DSL is the same for all resources.
List resources:
NamespaceList myNs = client.namespaces().list();
ServiceList myServices = client.services().list();
ServiceList myNsServices = client.services().inNamespace("default").list();
Get a resource:
Namespace myns = client.namespaces().withName("myns").get();
Service myservice = client.services().inNamespace("default").withName("myservice").get();
Delete:
Namespace myns = client.namespaces().withName("myns").delete();
Service myservice = client.services().inNamespace("default").withName("myservice").delete();
Editing resources uses the inline builders from the Kubernetes Model:
Namespace myns = client.namespaces().withName("myns").edit(n -> new NamespaceBuilder(n)
.editMetadata()
.addToLabels("a", "label")
.endMetadata()
.build());
Service myservice = client.services().inNamespace("default").withName("myservice").edit(s -> new ServiceBuilder(s)
.editMetadata()
.addToLabels("another", "label")
.endMetadata()
.build());
In the same spirit you can inline builders to create:
Namespace myns = client.namespaces().create(new NamespaceBuilder()
.withNewMetadata()
.withName("myns")
.addToLabels("a", "label")
.endMetadata()
.build());
Service myservice = client.services().inNamespace("default").create(new ServiceBuilder()
.withNewMetadata()
.withName("myservice")
.addToLabels("another", "label")
.endMetadata()
.build());
You can also set the apiVersion of the resource like in the case of SecurityContextConstraints :
SecurityContextConstraints scc = new SecurityContextConstraintsBuilder()
.withApiVersion("v1")
.withNewMetadata().withName("scc").endMetadata()
.withAllowPrivilegedContainer(true)
.withNewRunAsUser()
.withType("RunAsAny")
.endRunAsUser()
.build();
Following events
Use io.fabric8.kubernetes.api.model.Event
as T for Watcher:
client.events().inAnyNamespace().watch(new Watcher<>() {
@Override
public void eventReceived(Action action, Event resource) {
System.out.println("event " + action.name() + " " + resource.toString());
}
@Override
public void onClose(WatcherException cause) {
System.out.println("Watcher close due to " + cause);
}
});
Working with extensions
The kubernetes API defines a bunch of extensions like daemonSets
, jobs
, ingresses
and so forth which are all usable in the extensions()
DSL:
e.g. to list the jobs…
jobs = client.batch().jobs().list();
Loading resources from external sources
There are cases where you want to read a resource from an external source, rather than defining it using the clients DSL. For those cases the client allows you to load the resource from:
- A file (Supports both java.io.File and java.lang.String)
- A url
- An input stream
Once the resource is loaded, you can treat it as you would, had you created it yourself.
For example lets read a pod, from a yml file and work with it:
Pod refreshed = client.load('/path/to/a/pod.yml').fromServer().get();
client.load('/workspace/pod.yml').delete();
LogWatch handle = client.load('/workspace/pod.yml').watchLog(System.out);
Passing a reference of a resource to the client
In the same spirit you can use an object created externally (either a reference or using its string representation).
For example:
Pod pod = someThirdPartyCodeThatCreatesAPod();
client.resource(pod).delete();
Adapting the client
The client supports plug-able adapters. An example adapter is the OpenShift Adapter which allows adapting an existing KubernetesClient instance to an OpenShiftClient one.
For example:
KubernetesClient client = new KubernetesClientBuilder().build();
OpenShiftClient oClient = client.adapt(OpenShiftClient.class);
The client also support the isAdaptable() method which checks if the adaptation is possible and returns true if it does.
KubernetesClient client = new KubernetesClientBuilder().build();
if (client.isAdaptable(OpenShiftClient.class)) {
OpenShiftClient oClient = client.adapt(OpenShiftClient.class);
} else {
throw new Exception("Adapting to OpenShiftClient not support. Check if adapter is present, and that env provides /oapi root path.");
}
Adapting and close
Note that when using adapt() both the adaptee and the target will share the same resources (underlying http client, thread pools etc). This means that close() is not required to be used on every single instance created via adapt. Calling close() on any of the adapt() managed instances or the original instance, will properly clean up all the resources and thus none of the instances will be usable any longer.
Mocking Kubernetes
Along with the client this project also provides a kubernetes mock server that you can use for testing purposes.
The mock server is based on https://github.com/square/okhttp/tree/master/mockwebserver
but is empowered by the DSL and features provided by https://github.com/fabric8io/mockwebserver
.
The Mock Web Server has two modes of operation:
- Expectations mode
- CRUD mode
Expectations mode
It’s the typical mode where you first set which are the expected http requests and which should be the responses for each request. More details on usage can be found at: https://github.com/fabric8io/mockwebserver
This mode has been extensively used for testing the client itself. Make sure you check kubernetes-test.
To add a Kubernetes server to your test:
@Rule
public KubernetesServer server = new KubernetesServer();
CRUD mode
Defining every single request and response can become tiresome. Given that in most cases the mock webserver is used to perform simple crud based operations, a crud mode has been added. When using the crud mode, the mock web server will store, read, update and delete kubernetes resources using an in memory map and will appear as a real api server.
To add a Kubernetes Server in crud mode to your test:
@Rule
public KubernetesServer server = new KubernetesServer(true, true);
Then you can use the server like:
@Test
public void testInCrudMode() {
KubernetesClient client = server.getClient();
final CountDownLatch deleteLatch = new CountDownLatch(1);
final CountDownLatch closeLatch = new CountDownLatch(1);
//CREATE
client.pods().inNamespace("ns1").create(new PodBuilder().withNewMetadata().withName("pod1").endMetadata().build());
//READ
podList = client.pods().inNamespace("ns1").list();
assertNotNull(podList);
assertEquals(1, podList.getItems().size());
//WATCH
Watch watch = client.pods().inNamespace("ns1").withName("pod1").watch(new Watcher<>() {
@Override
public void eventReceived(Action action, Pod resource) {
switch (action) {
case DELETED:
deleteLatch.countDown();
break;
default:
throw new AssertionFailedError(action.toString().concat(" isn't recognised."));
}
}
@Override
public void onClose(WatcherException cause) {
closeLatch.countDown();
}
});
//DELETE
client.pods().inNamespace("ns1").withName("pod1").delete();
//READ AGAIN
podList = client.pods().inNamespace("ns1").list();
assertNotNull(podList);
assertEquals(0, podList.getItems().size());
assertTrue(deleteLatch.await(1, TimeUnit.MINUTES));
watch.close();
assertTrue(closeLatch.await(1, TimeUnit.MINUTES));
}
JUnit5 support through extension
You can use KubernetesClient mocking mechanism with JUnit5. Since it doesn’t support @Rule
and @ClassRule
there is dedicated annotation @EnableKubernetesMockClient
.
If you would like to create instance of mocked KubernetesClient
for each test (JUnit4 @Rule
) you need to declare instance of KubernetesClient
as shown below.
@EnableKubernetesMockClient
class ExampleTest {
KubernetesClient client;
@Test
public void testInStandardMode() {
...
}
}
In case you would like to define static instance of mocked server per all the test (JUnit4 @ClassRule
) you need to declare instance of KubernetesClient
as shown below.
You can also enable crudMode by using annotation field crud
.
@EnableKubernetesMockClient(crud = true)
class ExampleTest {
static KubernetesClient client;
@Test
public void testInCrudMode() {
// ...
}
}
Testing Against real Kubernetes API Server with Kube API Test
In order to test against real Kubernetes API the project provides a lightweight approach, thus starting up Kubernetes API Server and etcd binaries.
@EnableKubeAPIServer
class KubeAPITestSample {
static KubernetesClient client;
@Test
void testWithClient() {
// test using the client against real K8S API Server
}
}
For details see docs for Kube API Test.
Compatibility
Kubernetes
Starting from v5.5, the Kubernetes Client should be compatible with any supported Kubernetes cluster version.
We provide DSL methods (for example client.pods()
, client.namespaces()
, and so on) for the most commonly used Kubernetes resources. If the resource you’re looking for is not available through the DSL, you can always use the generic client.resource()
method to interact with it. You can also open a new issue to request the addition of a new resource to the DSL.
We provide Kubernetes Java model types (for example Pod
) and their corresponding builders (for example PodBuilder
) for every vanilla Kubernetes resource (and some extensions). If you don’t find a specific resource, and you think that it should be part of the Kubernetes Client, please open a new issue.
OpenShift
Starting from v5.5, the OpenShift Client should be compatible with any OpenShift cluster version currently supported by Red Hat. The Fabric8 Kubernetes Client is one of the few Kubernetes Java clients that provides full support for any supported OpenShift cluster version. If you find any incompatibility or something missing, please open a new issue.
Major Changes in Kubernetes Client 4.0.0
All the resource objects used here will be according to OpenShift 3.9.0 and Kubernetes 1.9.0. All the resource objects will give all the fields according to OpenShift 3.9.0 and Kubernetes 1.9.0
- SecurityContextConstraints has been moved to OpenShift client from Kubernetes Client
- Job dsl is in both
batch
andextensions
(Extensions is deprecated) - DaemonSet dsl is in both
apps
andextensions
(Extensions is deprecated) - Deployment dsl is in both
apps
andextensions
(Extensions is deprecated) - ReplicaSet dsl is in both
apps
andextensions
(Extensions is deprecated) - NetworkPolicy dsl is in both
network
andextensions
(Extensions is deprecated) - Storage Class moved from
client base DSL
tostorage
DSL - PodSecurityPolicies moved from
client base DSL
andextensions
to onlyextensions
- ThirdPartyResource has been removed.
Who uses Kubernetes & OpenShift Java client?
Extensions:
- Knative
- Tekton
- Volcano
- Istio
- Open Cluster Management
- Camel-k - Maven Central
Frameworks/Libraries/Tools:
- Arquillian Cube
- Apache Camel
- Apache Flink
- Apache Spark
- Jaeger Kubernetes
- Loom
- Microsoft Azure Libraries for Java
- Spinnaker Halyard
- Spring Cloud Connectors for Kubernetes
- Spring Cloud Kubernetes
CI Plugins:
- Deployment Pipeline Plugin (Jenkins)
- Kubernetes Elastic Agent (GoCD)
- Kubernetes Plugin (Jenkins)
- Kubernetes Pipeline Plugin (Jenkins)
- OpenShift Sync Plugin (Jenkins)
- Kubernetes Plugin (Teamcity from Jetbrains)
- Kubernetes Agents for Bamboo (WindTunnel Technologies)
Build Tools:
- Fabric8 Maven Plugin
- Eclipse JKube
- Gradle Kubernetes Plugin
Platforms:
- Apache Openwhisk
- Eclipse che
- Openshift.io (Launcher service)
- Spotify Styx
- Strimzi
- Syndesis
- StackGres
- Boomerang Flow
- Apache Kyuubi
Proprietary Platforms:
- vCommander
As our community grows, we would like to track keep track of our users. Please send a PR with your organization/community name.
Tests we run for every new Pull Request
There are the links of the Github Actions and Jenkins for the tests which run for every new Pull Request. You can view all the recent builds also.
- Regression Tests
- Unit Tests
To get the updates about the releases, you can join https://groups.google.com/forum/embed/?place=forum/fabric8-devclients
Kubectl Java Equivalents
This table provides kubectl
to Kubernetes Java Client mappings. Most of the mappings are quite straightforward and are one liner
operations. However, some might require slightly more code to achieve same result:
kubectl config view
ConfigViewEquivalent.java
kubectl config get-contexts
ConfigGetContextsEquivalent.java
kubectl config current-context
ConfigGetCurrentContextEquivalent.java
kubectl config use-context minikube
ConfigUseContext.java
kubectl config view -o jsonpath='{.users[*].name}'
ConfigGetCurrentContextEquivalent.java
kubectl get pods --all-namespaces
PodListGlobalEquivalent.java
kubectl get pods
PodListEquivalent.java
kubectl get pods -w
PodWatchEquivalent.java
kubectl get pods --sort-by='.metadata.creationTimestamp'
PodListGlobalEquivalent.java
kubectl run
PodRunEquivalent.java
kubectl create -f test-pod.yaml
PodCreateYamlEquivalent.java
kubectl exec my-pod -- ls /
PodExecEquivalent.java
kubectl attach my-pod
PodAttachEquivalent.java
kubectl delete pod my-pod
PodDelete.java
kubectl delete -f test-pod.yaml
PodDeleteViaYaml.java
kubectl cp /foo_dir my-pod:/bar_dir
UploadDirectoryToPod.java
kubectl cp my-pod:/tmp/foo /tmp/bar
DownloadFileFromPod.java
kubectl cp my-pod:/tmp/foo -c c1 /tmp/bar
DownloadFileFromMultiContainerPod.java
kubectl cp /foo_dir my-pod:/tmp/bar_dir
UploadFileToPod.java
kubectl logs pod/my-pod
PodLogsEquivalent.java
kubectl logs pod/my-pod -f
PodLogsFollowEquivalent.java
kubectl logs pod/my-pod -c c1
PodLogsMultiContainerEquivalent.java
kubectl port-forward my-pod 8080:80
PortForwardEquivalent.java
kubectl get pods --selector=version=v1 -o jsonpath='{.items[*].metadata.name}'
PodListFilterByLabel.java
kubectl get pods --field-selector=status.phase=Running
PodListFilterFieldSelector.java
kubectl get pods --show-labels
PodShowLabels.java
kubectl label pods my-pod new-label=awesome
PodAddLabel.java
kubectl annotate pods my-pod icon-url=http://goo.gl/XXBTWq
PodAddAnnotation.java
kubectl get configmap cm1 -o jsonpath='{.data.database}'
ConfigMapJsonPathEquivalent.java
kubectl create -f test-svc.yaml
LoadAndCreateService.java
kubectl create -f test-deploy.yaml
LoadAndCreateDeployment.java
kubectl set image deploy/d1 nginx=nginx:v2
RolloutSetImageEquivalent.java
kubectl scale --replicas=4 deploy/nginx-deployment
ScaleEquivalent.java
kubectl scale statefulset --selector=app=my-database --replicas=4
ScaleWithLabelsEquivalent.java
kubectl rollout restart deploy/d1
RolloutRestartEquivalent.java
kubectl rollout pause deploy/d1
RolloutPauseEquivalent.java
kubectl rollout resume deploy/d1
RolloutResumeEquivalent.java
kubectl rollout undo deploy/d1
RolloutUndoEquivalent.java
kubectl create -f test-crd.yaml
LoadAndCreateCustomResourceDefinition.java
kubectl create -f customresource.yaml
CustomResourceCreateDemo.java
kubectl create -f customresource.yaml
CustomResourceCreateDemoTypeless.java
kubectl get ns
NamespaceListEquivalent.java
kubectl create namespace test
NamespaceCreateEquivalent.java
kubectl apply -f test-resource-list.yml
CreateOrReplaceResourceList.java
kubectl get events
EventsGetEquivalent.java
kubectl top nodes
TopEquivalent.java
kubectl auth can-i create deployment.apps
CanIEquivalent.java
kubectl create -f test-csr-v1.yml
CertificateSigningRequestCreateYamlEquivalent.java
kubectl certificate approve my-cert
CertificateSigningRequestApproveYamlEquivalent.java
kubectl certificate deny my-cert
CertificateSigningRequestDenyYamlEquivalent.java
kubectl create -f quota.yaml --namespace=default
CreateResourceQuotaInNamespaceYamlEquivalent.java