This client provides access to the full Kubernetes & OpenShift 3 REST APIs via a fluent DSL.
Usage
Creating a client
The easiest way to create a client is:
KubernetesClient client = new DefaultKubernetesClient();
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 DefaultOpenShiftClient();
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:
kubernetes.master
/KUBERNETES_MASTER
kubernetes.api.version
/KUBERNETES_API_VERSION
kubernetes.oapi.version
/KUBERNETES_OAPI_VERSION
kubernetes.trust.certificates
/KUBERNETES_TRUST_CERTIFICATES
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
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.tryKubeConfig
/KUBERNETES_AUTH_TRYKUBECONFIG
kubernetes.auth.tryServiceAccount
/KUBERNETES_AUTH_TRYSERVICEACCOUNT
kubernetes.auth.token
/KUBERNETES_AUTH_TOKEN
kubernetes.watch.reconnectInterval
/KUBERNETES_WATCH_RECONNECTINTERVAL
kubernetes.watch.reconnectLimit
/KUBERNETES_WATCH_RECONNECTLIMIT
kubernetes.user.agent
/KUBERNETES_USER_AGENT
kubernetes.tls.versions
/KUBERNETES_TLS_VERSIONS
kubernetes.truststore.file
/KUBERNETES_TRUSTSTORE_FILE
kubernetes.truststore.passphrase
/KUBERNETES_TRUSTSTORE_PASSPHRASE
kubernetes.keystore.file
/KUBERNETES_KEYSTORE_FILE
kubernetes.keystore.passphrase
/KUBERNETES_KEYSTORE_PASSPHRASE
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 DefaultKubernetesClient(config);
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()
.editMetadata()
.addToLabels("a", "label")
.endMetadata()
.done();
Service myservice = client.services().inNamespace("default").withName("myservice").edit()
.editMetadata()
.addToLabels("another", "label")
.endMetadata()
.done();
In the same spirit you can inline builders to create:
Namespace myns = client.namespaces().createNew()
.editMetadata()
.withName("myns")
.addToLabels("a", "label")
.endMetadata()
.done();
Service myservice = client.services().inNamespace("default").createNew()
.editMetadata()
.withName("myservice")
.addToLabels("another", "label")
.endMetadata()
.done();
Following events
Use io.fabric8.kubernetes.api.model.Event
as T for Watcher:
client.events().inAnyNamespace().watch(new Watcher<Event>() {
@Override
public void eventReceived(Action action, Event resource) {
System.out.println("event " + action.name() + " " + resource.toString());
}
@Override
public void onClose(KubernetesClientException 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.extensions().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();
Boolean deleted = 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 a reference or using its string representation.
For example:
Pod pod = someThirdPartyCodeThatCreatesAPod();
Boolean deleted = 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 DefaultKubernetesClient();
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 DefaultKubernetesClient();
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.