istio-java-api

**Note**

= This project is now deprecated. Please use the Istio client in the https://github.com/fabric8io/kubernetes-client project starting with version 5.11.0.










= istio-java-api

A project to generate a Java API for https://istio.io[Istio]'s domain allowing, in particular, the generation of Istio deployment
descriptors.This project is inspired by https://github.com/fabric8io/kubernetes-model[Fabric8's kubernetes-model] and relies on
the same approach: a Go program uses Go reflection to generate a http://json-schema.org[JSON Schema] which is then used by
https://github.com/joelittlejohn/jsonschema2pojo[jsonschema2pojo] to generate Java classes. jsonschema2pojo is configured to use
a custom annotator, `IstioTypeAnnotator` (found in the `istio-model-annotator` module), to add
(https://github.com/fasterxml/jackson[Jackson], https://jcp.org/en/jsr/detail?id=380[Bean Validation - JSR 380] and
https://github.com/sundrio/sundrio[sundrio] annotations.Sundrio is used generate idiomatic builder and DSL Java classes.
Jackson is used to output JSON or YAML representation of the Java objects when needed.

== Usage

Please take a look at the tests in `istio-model/src/test/java` to see how the API can be used.
You can also take a look at the
https://github.com/metacosm/istio-test-dsl project which demonstrates an end-to-end scenario using the Fabric8 OpenShift adapter and this API to send Istio artifacts to a running OpenShift cluster configured on which Istio is set up.

[Note]
====
Starting with the `1.7.7` of this API, the bundled version of the Fabric8 Kubernetes client has been upgraded to use the non-backwards compatible `5.x` versions.
While this might not be an issue for most users of this API, it's still worth noting.
====

== Building instructions

If you only want to build the current version of the API and don't intend on modifying how the JSON Schema is generated, you can build simply using `mvn clean install` as the project contains a pre-generated version of the schema.If you need to re-generate the classes from a newer version of the API, since the build relies on Go introspection, you will need to set up a Go programming environment.

=== Building the Java API

You will need to https://golang.org/doc/install[install Go] and `make`.
Run `make`.
This will build the `generate` command line tool from Go and then run it to generate a JSON Schema in
`istio-model/src/main/resources/schema/istio-schema.json`.
A Maven build is then issued using the `jsonschema2pojo` Maven plugin to generate Java classes in `istio-model/target/generated-sources` and generate a Jar file containing the compiled version of these classes along with the JSON schema, ready to be used.

You can *clean* everything using `make clean`, only *generate the schema* using `make schema` or only generate the Java classes from an already generated schema such as the provided one using `mvn clean install`.

=== Updating the Java API when Istio is updated

NOTE: The process is not completely reproducible at this time.
:(

[source,bash]
----
# update to the latest istio version, rebuild crd list and packages
make metadata
# build using strict mode
make strict
# fix any issue, iterate… :)
----

You can also re-generate the properties files that are used to determine which
https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/[Kubernetes Custom Resource Definitions (CRDs)]
are specified by Istio.
These files are located in `istio-common/src/main/resources/`, one for each kind of supported CRDs and can be generated using `make metadata`.
You can also re-generate the CSV file that is used to map Istio Go packages to Java packages.
The file is located at
`istio-common/src/main/resources/packages.csv` and can be generated using `make metadata`.