Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Publishing Adapters and Templates to istio.io
If you've written a great new Mixer adapter and you'd like to make it available to as many Istio users as possible, you should consider listing your adapter on istio.io. It's easy.
Document your adapter or template. To create adapters and templates, you need to author proto files. Please fully document the proto messages and individual fields, with an eye towards an operator that is trying to use your component. Example YAML is highly desirable in this documentation. You can see many examples of properly documented adapters in the core Mixer adapters.
Annotate your adapter or template. To get your documentation on istio.io, it needs to have a few special annotations. Those are introduced via a stand-alone comment at the top of your proto file. These special comments are of the form:
// $keyword: value
These comments are used by Istio's documentation machinery to integrate your documentation into the overall website. The set of keywords that you can use are:
Keyword Required Description title Yes The short name of your component. description Yes A one sentence description of your component. location Yes The URL within istio.io where your component's documentation should go. This should be
https://istio.io/docs/reference/config/policy-and-telemetry/adapters/*adapter name*.htmlfor adapters and
https://istio/docs/reference/config/policy-and-telemetry/templates/*template name*.htmlfor templates.
provider No The name of your company, or your name if you're an individual contributor. contact_email No A contact email address for customers trying to get in touch with you. support_link No A URL to a support website for the component. latest_release_link No A link to a release page showing the latest available release of your component. helm_chart_link No A link to a Helm chart allowing users to install your component. source_link No A link to the source code for your component. istio_versions No A comma-separated list of Istio versions that you have tested your component with. Enclose this list in double-quotes. supported_templates No For adapters, a comma-separated list of templates the adapter supports. logo_link No A link to a logo to display on the documentation page.
Build your component. Building your component should result in a
.pb.htmlfile which holds the documentation for your component. You need to commit that
.pb.htmlfile to a public Git repo so that the Istio documentation machinery can find it.
Register your adapter or template. Once you have checked in the
.pb.htmlfile to your public Git repo, you need to head over to istio/istio.io and create a PR that adds your repo's address to the REPOS variable in the
scripts/grab_reference_docs.shscript. Once your PR is committed, the Istio documentation machinery will eventually run, discover your repo, then find your
.pb.htmlfile, and publish it to istio.io alongside all the other adapters.
Here's an example of what all these annotations end up looking like once the docs are published.