Skip to content

Commit 341ee71

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #1397 from yue9944882/doc/wiki
Triming readme page content by referencing wiki pages
2 parents 7f61072 + 7943328 commit 341ee71

File tree

1 file changed

+16
-249
lines changed

1 file changed

+16
-249
lines changed

‎README.md

Lines changed: 16 additions & 249 deletions
Original file line numberDiff line numberDiff line change
@@ -7,260 +7,27 @@
77

88
Java client for the [kubernetes](http://kubernetes.io/) API.
99

10-
## Client versioning
11-
The Java client uses Semantic Versioning. We increment the major version number whenever we
12-
regenerate the client for a new Kubernetes release version (see table below). Whenever we do
13-
this there are new APIs added and possibly breaking changes in the generated Kubernetes API
14-
Stubs. Whenever you upgrade a major version, be prepared for potential breaking changes.
10+
## To start using Kubernetes Java Client
1511

16-
## Installation
12+
See the wiki page and documentation [here](https://github.com/kubernetes-client/java/wiki).
1713

18-
To install the Java client library to your local Maven repository, simply execute:
14+
- [Installation](https://github.com/kubernetes-client/java/wiki/1.-Installation)
15+
- [Client Versioning and Compatibility](https://github.com/kubernetes-client/java/wiki/2.-Versioning-and-Compatibility)
16+
- [Code Examples](https://github.com/kubernetes-client/java/wiki/3.-Code-Examples)
1917

20-
```shell
21-
git clone --recursive https://github.com/kubernetes-client/java
22-
cd java
23-
mvn install
24-
```
18+
## Development
2519

26-
Refer to the [official documentation](https://maven.apache.org/plugins/maven-deploy-plugin/usage.html) for more information.
20+
- [Development and Contributing](https://github.com/kubernetes-client/java/wiki/4.-Development-and-Contributing)
21+
- [Generate Java CRD Models](https://github.com/kubernetes-client/java/wiki/5.-Generate-Java-CRD-Model)
22+
- [Known Issues](https://github.com/kubernetes-client/java/wiki/6.-Known-Issues)
2723

28-
### Maven users
24+
## Support
2925

30-
Add this dependency to your project's POM:
26+
If you need support, start with checking whether you're hitting known issues. If that doesn't work, please [open an issue](https://github.com/kubernetes-client/java/issues/new)
27+
to describe the cases. Additionally, before you file an issue, please search [existing issues](https://github.com/kubernetes-client/java/issues)
28+
to see if your issue is
29+
already covered.
3130

32-
```xml
33-
<dependency>
34-
<groupId>io.kubernetes</groupId>
35-
<artifactId>client-java</artifactId>
36-
<version>10.0.0</version>
37-
</dependency>
38-
```
31+
You can also reach out to us via [#kubernetes-client](https://kubernetes.slack.com/messages/kubernetes-clients/) slack
32+
channel.
3933

40-
### Gradle users
41-
42-
```groovy
43-
compile 'io.kubernetes:client-java:10.0.0'
44-
```
45-
46-
### Others
47-
48-
At first generate the JAR by executing:
49-
50-
```
51-
git clone --recursive https://github.com/kubernetes-client/java
52-
cd java/kubernetes
53-
mvn package
54-
```
55-
56-
Then manually install the following JARs:
57-
58-
* target/client-java-api-10.0.1-SNAPSHOT.jar
59-
* target/lib/*.jar
60-
61-
## Known Issues
62-
63-
##### 1. Exception on deleting resources: "java.lang.IllegalStateException: Expected a string but was BEGIN_OBJECT..."
64-
65-
This is happening because openapi schema from kubernetes upstream doesn't match its implementation due to
66-
the limitation of openapi v2 schema expression [#86](https://github.com/kubernetes-client/java/issues/86).
67-
Consider either catch and ignore the JsonSyntaxException or do the deletion in the following form:
68-
69-
- Use Kubectl equivalence, see examples [here](https://github.com/kubernetes-client/java/blob/6fa3525189d9e50d9b07016155642ddf59990905/e2e/src/test/groovy/io/kubernetes/client/e2e/kubectl/KubectlNamespaceTest.groovy#L69-L72)
70-
- Use generic kubernetes api, see examples [here](https://github.com/kubernetes-client/java/blob/6fa3525189d9e50d9b07016155642ddf59990905/examples/src/main/java/io/kubernetes/client/examples/GenericClientExample.java#L56)
71-
72-
## Example
73-
74-
We prepared a few examples for common use-cases which are shown below:
75-
- __Configuration__:
76-
- [InClusterClientExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/InClusterClientExample.java):
77-
Configure a client while running inside the Kubernetes cluster.
78-
- [KubeConfigFileClientExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/KubeConfigFileClientExample.java):
79-
Configure a client to access a Kubernetes cluster from outside.
80-
- __Basics__:
81-
- [SimpleExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/Example.java):
82-
Simple minimum example of how to use the client.
83-
- [ProtoExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/ProtoExample.java):
84-
Request/receive payloads in protobuf serialization protocol.
85-
- ([5.0.0+](https://github.com/kubernetes-client/java/tree/client-java-parent-5.0.0)) [PatchExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/PatchExample.java):
86-
Patch resource objects in various supported patch formats, equal to `kubectl patch`.
87-
- [FluentExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/FluentExample.java):
88-
Construct arbitrary resource in a fluent builder style.
89-
- [YamlExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/YamlExample.java):
90-
Suggested way to load or dump resource in Yaml.
91-
- __Streaming__:
92-
- [WatchExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/WatchExample.java):
93-
Subscribe watch events from certain resources, equal to `kubectl get <resource> -w`.
94-
- [LogsExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/LogsExample.java):
95-
Fetch logs from running containers, equal to `kubectl logs`.
96-
- [ExecExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/ExecExample.java):
97-
Establish an "exec" session with running containers, equal to `kubectl exec`.
98-
- [PortForwardExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/PortForwardExample.java):
99-
Maps local port to a port on the pod, equal to `kubectl port-forward`.
100-
- [AttachExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/AttachExample.java):
101-
Attach to a process that is already running inside an existing container, equal to `kubectl attach`.
102-
- [CopyExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/CopyExample.java):
103-
Copy files and directories to and from containers, equal to `kubectl cp`.
104-
- [WebSocketsExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/WebSocketsExample.java):
105-
Establish an arbitrary web-socket session to certain resources.
106-
- __Advanced__: (NOTE: The following example requires `client-java-extended` module）
107-
- ([5.0.0+](https://github.com/kubernetes-client/java/tree/client-java-parent-5.0.0)) [InformerExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/InformerExample.java):
108-
Build an informer which list-watches resources and reflects the notifications to a local cache.
109-
- ([5.0.0+](https://github.com/kubernetes-client/java/tree/client-java-parent-5.0.0)) [PagerExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/PagerExample.java):
110-
Support Pagination (only for the list request) to ease server-side loads/network congestion.
111-
- ([6.0.0+](https://github.com/kubernetes-client/java/tree/client-java-parent-6.0.0)) [ControllerExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/ControllerExample.java):
112-
Build a controller reconciling the state of world by list-watching one or multiple resources.
113-
- ([6.0.0+](https://github.com/kubernetes-client/java/tree/client-java-parent-6.0.0)) [LeaderElectionExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/LeaderElectionExample.java):
114-
Leader election utilities to help implement HA controllers.
115-
- ([9.0.0+](https://github.com/kubernetes-client/java/tree/client-java-parent-9.0.0)) [SpringIntegrationControllerExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/SpringControllerExample.java):
116-
Building a kubernetes controller based on spring framework's bean injection, see additional documentation [here](./docs/java-controller-tutorial-rewrite-rs-controller.md).
117-
- ([9.0.0+](https://github.com/kubernetes-client/java/tree/client-java-parent-9.0.0)) [GenericKubernetesClientExample](./examples/examples-release-10/src/main/java/io/kubernetes/client/examples/GenericClientExample.java):
118-
Construct a generic client interface for any kubernetes types, including CRDs.
119-
120-
121-
__list all pods__:
122-
123-
```java
124-
import io.kubernetes.client.openapi.ApiClient;
125-
import io.kubernetes.client.openapi.ApiException;
126-
import io.kubernetes.client.openapi.Configuration;
127-
import io.kubernetes.client.openapi.apis.CoreV1Api;
128-
import io.kubernetes.client.openapi.models.V1Pod;
129-
import io.kubernetes.client.openapi.models.V1PodList;
130-
import io.kubernetes.client.util.Config;
131-
132-
import java.io.IOException;
133-
134-
public class Example {
135-
public static void main(String[] args) throws IOException, ApiException{
136-
ApiClient client = Config.defaultClient();
137-
Configuration.setDefaultApiClient(client);
138-
139-
CoreV1Api api = new CoreV1Api();
140-
V1PodList list = api.listPodForAllNamespaces(null, null, null, null, null, null, null, null, null);
141-
for (V1Pod item : list.getItems()) {
142-
System.out.println(item.getMetadata().getName());
143-
}
144-
}
145-
}
146-
```
147-
148-
__watch on namespace object__:
149-
150-
```java
151-
import com.google.gson.reflect.TypeToken;
152-
import io.kubernetes.client.openapi.ApiClient;
153-
import io.kubernetes.client.openapi.ApiException;
154-
import io.kubernetes.client.openapi.Configuration;
155-
import io.kubernetes.client.openapi.apis.CoreV1Api;
156-
import io.kubernetes.client.openapi.models.V1Namespace;
157-
import io.kubernetes.client.util.Config;
158-
import io.kubernetes.client.util.Watch;
159-
160-
import java.io.IOException;
161-
162-
public class WatchExample {
163-
public static void main(String[] args) throws IOException, ApiException{
164-
ApiClient client = Config.defaultClient();
165-
Configuration.setDefaultApiClient(client);
166-
167-
CoreV1Api api = new CoreV1Api();
168-
169-
Watch<V1Namespace> watch = Watch.createWatch(
170-
client,
171-
api.listNamespaceCall(null, null, null, null, null, 5, null, null, Boolean.TRUE, null, null),
172-
new TypeToken<Watch.Response<V1Namespace>>(){}.getType());
173-
174-
for (Watch.Response<V1Namespace> item : watch) {
175-
System.out.printf("%s : %s%n", item.type, item.object.getMetadata().getName());
176-
}
177-
}
178-
}
179-
```
180-
181-
More examples can be found in [examples](examples) folder. To run examples, run this command:
182-
183-
```shell
184-
mvn exec:java -Dexec.mainClass="io.kubernetes.client.examples.Example"
185-
```
186-
## Model Classes from Popular CRDs
187-
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.
188-
* [cert-manager](client-java-contrib/cert-manager)
189-
* [prometheus operator](client-java-contrib/prometheus-operator)
190-
191-
## Documentation
192-
193-
All APIs and Models' documentation can be found at the [Generated client's docs](https://github.com/kubernetes-client/java/tree/master/kubernetes/docs)
194-
195-
## Compatibility
196-
197-
| client version | 1.13 | 1.14 | 1.15 | 1.16 | 1.17 | 1.18 |
198-
|------------------|-----------|----------|----------|-----------|----------|----------|
199-
| 5.0.0 | ✓ | - | - | x | x | x |
200-
| 6.0.1 | + | ✓ | - | - | x | x |
201-
| 7.0.0 | + | + | ✓ | - | - | x |
202-
| 8.0.2 | + | + | + | ✓ | - | - |
203-
| 9.0.2 | + | + | + | + | ✓ | - |
204-
| 10.0.0 | + | + | + | + | + | ✓ |
205-
206-
Key:
207-
208-
* `✓` Exactly the same features / API objects in both java-client and the Kubernetes
209-
version.
210-
* `+` java-client has features or api objects that may not be present in the
211-
Kubernetes cluster, but everything they have in common will work.
212-
* `-` The Kubernetes cluster has features the java-client library can't use
213-
(additional API objects, etc).
214-
* `x` The Kubernetes cluster has no guarantees to support the API client of
215-
this version, as it only promises _n_-2 version support. It is not tested,
216-
and operations using API versions that have been deprecated and removed in
217-
later server versions won't function correctly.
218-
219-
See the [CHANGELOG](./CHANGELOG.md) for a detailed description of changes
220-
between java-client versions.
221-
222-
## Contributing
223-
224-
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on how to contribute.
225-
226-
### Code of Conduct
227-
228-
Participation in the Kubernetes community is governed by the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
229-
230-
# Development
231-
232-
## Update the generated code.
233-
234-
The code is generated by the [openapi-generator project](https://github.com/OpenAPITools/openapi-generator).
235-
236-
We have built general purpose cross-language tools for generating code, it is hosted in the
237-
[kubernetes-client/gen](https://github.com/kubernetes-client/gen) repository.
238-
239-
To get started, in a root directory that is _not_ your `java` client directory, for example your
240-
directory layout could be:
241-
```
242-
${HOME}/
243-
src/
244-
gen/
245-
java/
246-
...
247-
```
248-
249-
Then to clone the `gen` repository, you would run:
250-
251-
```sh
252-
cd ${HOME}/src
253-
git clone https://github.com/kubernetes-client/gen
254-
export GEN_ROOT=${PWD}
255-
```
256-
257-
Then to update the client and run the formatter:
258-
259-
```sh
260-
cd ${HOME}/src/java
261-
${GEN_ROOT}/gen/openapi/java.sh kubernetes ./settings
262-
./mvnw spotless:apply
263-
```
264-
265-
This should run through a long-ish build process involving `docker` and eventually result in a new set of
266-
generated code in the `kubernetes` directory.

0 commit comments

Comments
 (0)