A project to generate a Java API for Istio's domain allowing, in particular, the generation of Istio deployment
descriptors. This project is inspired by Fabric8’s kubernetes-model and relies on
the same approach: a Go program uses Go reflection to generate a JSON Schema which is then used by
jsonschema2pojo to generate Java classes. jsonschema2pojo is configured to use
a custom annotator, IstioTypeAnnotator
(found in the istio-model-annotator
module), to add
(Jackson, Bean Validation - JSR 380 and
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.
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.
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.
In particular, you will need to install Go and check the code for this project within your
$GOPATH/src
hierarchy:
cd $GOPATH/src
mkdir -p github.com/snowdrop
cd github.com/snowdrop
git clone [email protected]:snowdrop/istio-java-api.git
cd istio-java-api
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
.
If any of the Go files are changed in such a way that new imports are required, you will need to run dep ensure
at the top level of the project in order to update the vendor
information otherwise you might run into issues
when building the project.
Note
|
The process is not completely reproduceable at this time. :( |
# download istio and api source
go get -u istio.io/istio
go get -u istio.io/api
cd $GOPATH/src/istio.io/istio
# checkout the istio version
git checkout <istio version>
# look for the constraint on the istio.io/api version in Gopkg.toml, which the following should help with:
grep -C 3 "istio.io/api" $GOPATH/src/istio.io/istio/Gopkg.toml | grep -A 3 "constraint"
cd $GOPATH/src/istio.io/api
# checkout the associated api version
git checkout <api version>
cd $GOPATH/src/github.com/snowdrop/istio-java-api
# log in to an OpenShift cluster with the target Istio version installed
oc login ...
# rebuild crd list and packages
make crd
make packages
# build using strict mode
make strict
You can also re-generate the properties files that are used to determine which
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 crd
. Right now, though, this command requires installing the
OpenShift Client and an active administrative connection
(via oc login
) to an OpenShift cluster on which Istio is installed.
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 packages
.