Publishing Adapters and Templates to istio.io

Martin Taillefer edited this page Oct 5, 2018 · 6 revisions

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.

  1. 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.

  2. 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*.html for adapters and https://istio/docs/reference/config/policy-and-telemetry/templates/*template name*.html for 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.
  3. Build your component. Building your component should result in a .pb.html file which holds the documentation for your component. You need to commit that .pb.html file to a public Git repo so that the Istio documentation machinery can find it.

  4. Register your adapter or template. Once you have checked in the .pb.html file 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.sh script. Once your PR is committed, the Istio documentation machinery will eventually run, discover your repo, then find your .pb.html file, 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.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.