maistra / maistra.github.io Goto Github PK

This is the source for maistra.io.

License: Apache License 2.0

HTML 26.47% CSS 41.40% Ruby 0.05% JavaScript 23.31% Shell 3.52% Makefile 0.94% Go 4.31%

maistra.github.io's Introduction

Issues for this repository are disabled

Issues for this repository are tracked in Red Hat Jira. Please head to https://issues.redhat.com/browse/MAISTRA in order to browse or open an issue.

OpenShift Service Mesh

This repository contains documentation for the community release of OpenShift Service Mesh, based on the upstream Istio project. This README provides information about this documentation repository. The site can be viewed at maistra.io.

Tooling

Maistra has a variety of tooling located in the tools directory.

checkLinks.sh CheckLinks is a wrapper around the html-proofer tool that runs on pull requests to make sure that links are valid.
runLinter.sh We use the Vale linter to validate our documentation. This script is a wrapper that runs on pull requests to verify documentation.
updateFields.sh Maistra ties together several different tools and exposes the ability to configure all of them through the ServiceMeshControlPlane. This script keeps everything in sync.

Getting Started

The Maistra documentation is written in [AsciiDoc](http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/). To generate the documentation, you should install the following tools:

Hugo
Asciidoctor
Text editor of your choice, for example the Atom text editor has several useful packages that make it easier to work with AsciiDoc and Hugo.

Repository Structure

Hugo assumes that the same structure that organizes your source content is used to organize the rendered site.

This repository uses the following directory structure:

├── [archetypes] - Can be used to define content, for example you can set default tags or categories and define types such as a post, tutorial or product here.
├── [topics] - Contains all the content files.
|   ├── Blog -- This directory is used to render the Maistra blog, which is rendered on the fly from a collection of RSS feeds.
|   ├── Docs -- This directory contains
│   │   ├── .adoc (AsciiDoc topic files)
│   ├── DRAFTS - This directory is intended for topic stubs, topics that need to be written, and in-progress drafts. The Hugo config file is set to ignore this directory and its contents.
│   │   ├── .adoc (AsciiDoc topic files)
├── [data] - Site data such a localization configurations go here.
├── [layouts] -  Layouts for the Go html/template library which Hugo utilizes.  Note that themes override layouts.
├── [static] - Any static files here will be compiled into the final website.
|   ├──  img - This directory contains all the images.  Hugo expects this directory name.
│   │  ├── .png
├── [themes] - This directory contains the theme for the site.
├── config.toml - Main Hugo configuration file, used to define the websites title, language, URLs etc.
├── README.md (This file)

Docs Header

Content in the docs directory require the following headers to be populated in order to be listed in the docs:

---
title: "Bookinfo"
type: "document"
category: "Examples"
description: "Bookinfo is an example application that shows you how to set up and monitor a service mesh using Istio."
---

For more information about writing modular documentation, see the [Modular Documentation Reference Guide](redhat-documentation.github.io/modular-docs/).

Previewing Changes Locally

Hugo provides its own web server which builds and serves the site. By default Hugo will also watch your files for any changes you make and automatically rebuild the site. It will then live reload any open browser pages and push the latest content to them.

To start the Hugo server run the following command: ` $ make serve `

Content can be verified using the linter and link checker: ` $ make check-links lint `

The full site output can be produced using the following command: ` $ make build `

Previewing Changes locally in a running container

If you want to test your changes without installing Hugo, you can verify the Maistra website in a docker container. You can build and test your changes similar to the local installation. The commands are a little different.

To start the Hugo server run the following command: ` $ make docker-serve `

Content can be verified using the linter and link checker: ` $ make docker-check-links docker-lint `

The full site output can be produced using the following command: ` $ make docker-build `

For the local test this image is used: quay.io/maistra-dev/maistra-builder:2.0. You can find the image source code here: https://github.com/maistra/test-infra

Releases

Release content in Maistra.io is driven by a combination of two files in the data directory:

data/release.yaml selects the latest release of Maistra to generate content from
data/releases/release.yaml, where release.yaml is the Maistra version, contains common information about the release. It contains the following fields:

Submitting a Pull Request

You can close a GitHub issue from a Pull Request. All you have to do is include the [special keyword syntax] (help.github.com/articles/closing-issues-using-keywords/) (for example, “fixes #5) in the body of your Pull Request. When the pull request is merged into your repository’s default branch, the corresponding issue is automatically closed.

Commit messages against Jira should start with the project name associated with the PR. If the PR is to address MAISTRA-123 then the commit message for the PR must start with "MAISTRA-123 " and then followed by the detailed commit message (no semi-column or dash between the Jira ID and text, no brackets… just a space).

maistra.github.io's People

Contributors

Stargazers

Watchers

maistra.github.io's Issues

Add 404 checking to CI jobs

While attempting to read the documentation I found a number of broken links on maistra.io. As a part of publishing the site a CI job should be added to check for broken links. Not advocating for any specific tool, but muffet got the job done nicely, minimized annoying dependencies, and exits non-zero when problems are found:

$ muffet -e .*\.nip\.io -e .*GATEWAY_URL.*  https://maistra.io
https://maistra.io/docs/examples/bookinfo/
	404	https://maistra.io/docs/getting_started/application-requirements/
	404	https://maistra.io/docs/getting_started/automatic-injection/
	404	https://maistra.io/docs/installation/install
https://maistra.io/docs/installation/automatic-injection/
	id #servicemesh_member_roll not found	https://maistra.io/docs/installation/controlplane#servicemesh_member_roll
https://maistra.io/docs/monitoring_and_tracing/prometheus/
	404	https://maistra.io/docs/monitoring_and_tracing/examples/bookinfo/#cleanup
https://maistra.io/docs/monitoring_and_tracing/grafana/
	id #cleanup not found	https://maistra.io/docs/examples/bookinfo/#cleanup
https://maistra.io/docs/examples/mesh-wide_mtls/
	id #_cluster_scoped_custom_resources not found	https://maistra.io/docs/comparison-with-istio/#_cluster_scoped_custom_resources
https://maistra.io/docs/monitoring_and_tracing/jaeger-tracing/
	404	https://maistra.io/docs/monitoring_and_tracing/examples/bookinfo/#cleanup
https://maistra.io/docs/comparison-with-istio/
	404	https://maistra.io/examples/mesh-wide_mtls/
	404	https://maistra.io/examples/mesh-wide_rbac/
https://maistra.io/contribute/
	id #writing-concepts not found	https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc#writing-concepts

Incorrect resource example for ServiceMeshMember in install docs

In the file maistra.github.io/topics/docs/installation/configuring-members.adoc

and visible here:
https://maistra.io/docs/installation/configuring-members/

The ServiceMeshMemberRole and ServiceMeshMember are using the same snippet. I looked in the snippets folder and there wasn't one for SMM - probably needs to get created and then referenced properly.

Installation instructions

On the getting started page, there is a "Custom Installation" section - but there is no actual instructions for downloading and setting up the environment.

Titles mentions "Documentation for Hugo Learn Theme" on Search engines.

Many pages has titles showing on the browser that is not relevant to the content showing in the browser and subsequently search results

Minimum resources for control plane

Hello,

During an installation of the Service Mesh Control Plane, we ran into an issue that was caused by too small default requests and default limits in the limit rate of the project. We didn't specify any resources (requests/limits) in the Service Mesh Control Plane. What would be the minimal resource setting to running the Service Mesh Control Plane for testing purposes? Is my assumption correct that, if I update the resources in the Service Mesh Control Plane, these changes will be reflected in the deployment? In the general section does the attribute Proxy refer to the sidecar container proxy or which proxy is meant?

Kind regards,

Olaf

Improve formatting for monitoring and tracing on non-wide screens.

See
https://maistra.io/docs/monitoring_and_tracing/

If I expand the window a little it becomes centered as expected but still with a thick border surrounding.

As opposed to the pages immediately following which displayed just fine on non-wide screens

Docs point to very old version of istiooc

The readme points to the /openshift-istio/ repo, which says to get an old version of istiooc to get started.
Maistra docs should explain how to get started with the tooling from within the Maistra repo.

Bookinfo mutual TLS destination rules example

Hello,
I am trying to do the Bookinfo example from Maistra documentation.

Under the section Add default destination rules, for the second case where I did enable mutual TLS: I think the actual oc command lacks.

It is written in the current doc:

destinationrule.networking.istio.io/productpage configured
destinationrule.networking.istio.io/reviews configured
destinationrule.networking.istio.io/ratings configured
destinationrule.networking.istio.io/details configured

Instead of (I assume it should be written):

oc -n ${BOOKINFO_NS} apply -f  https://raw.githubusercontent.com/maistra/istio/maistra-2.0/samples/bookinfo/networking/destination-rule-all-mtls.yaml

# result
destinationrule.networking.istio.io/productpage configured
destinationrule.networking.istio.io/reviews configured
destinationrule.networking.istio.io/ratings configured
destinationrule.networking.istio.io/details configured

I refer to the following repository: https://github.com/maistra/istio/tree/maistra-2.0/samples/bookinfo/networking

In this OpenShift 4.5 Doc, they suggest the following from maistra-1.1:

## If you enabled mutual TLS:

$ oc apply -n bookinfo -f https://raw.githubusercontent.com/Maistra/istio/maistra-1.1/samples/bookinfo/networking/destination-rule-all-mtls.yaml

Note the file destination-rule-all-mtls.yaml is the same for maistra-1.1 and maistra-2.0.

Mutal TLS Maistra Bookinfo example not working ?

However, after I set the destination rules with the mTLS, I can still reach the Bookinfo service/web page trough HTTP.

At this point, I was expecting to reach Bookinfo page trough HTTPS.

What am I missing?

oc -n ${BOOKINFO_NS} apply -f  https://raw.githubusercontent.com/maistra/istio/maistra-2.0/samples/bookinfo/networking/destination-rule-all-mtls.yaml

# result
destinationrule.networking.istio.io/productpage unchanged
destinationrule.networking.istio.io/reviews unchanged
destinationrule.networking.istio.io/ratings unchanged
destinationrule.networking.istio.io/details unchanged



curl -o /dev/null -s -w "%{http_code}\n" http://${GATEWAY_URL}/productpage

# result
200

Sofware version & environment

OKD cluster version: 4.5.0-0.okd-2020-09-04-180756

  Kernel Version:                         5.6.19-300.fc32.x86_64
  OS Image:                               Fedora CoreOS 32.20200629.3.0
  Operating System:                       linux
  Architecture:                           amd64
  Container Runtime Version:              cri-o://1.18.2
  Kubelet Version:                        v1.18.3
  Kube-Proxy Version:                     v1.18.3

Operator name	Version	vendor
Elastic Cloud on Kubernetes	1.2.1	provided by Elastic
Grafana Operator	3.5.0	provided by Red Hat
Community Jaeger Operator	1.19.0	provided by CNCF
Kiali Operator	1.22.0	provided by Kiali
Maistra Service Mesh	1.1.1	provided by Red Hat, Inc.

Other issue in the doc

I also think that there might be a mistake or a bug in how the spec.ressources default values are dealt with. See this other issue about spec.resources.limits for Jaeger.

Bring Back OKD 3.11 Installation Information

There's a fair chunk of pre-requisite information missing that relates to actually standing up a Maistra istio installation on OKD 3.11, can that be returned please?

Also, can we have more specific information pertaining to how to install Maistra 1.1 on OKD 3.11? Unless OKD 3.11 is no longer supported - in which case this question is no longer valid.