Adding documentation for Jaeger operator #258
Conversation
Signed-off-by: Julie Stickler <[email protected]>
There was a problem hiding this comment.
I haven't reviewed the actual documentation as I am not familiar with Operators.
I would suggest mentioning this page in the deployment.md, because currently it only mentions the templates and openshift repositories.
If these docs come from README in the operator repo, I would recommend removing them from there after this PR is merged, to avoid duplication and confusion about which version is more current.
There was a problem hiding this comment.
Some initial comments - will go through in more detail this afternoon.
Wondering whether it would be better to replace the references in the deployment page to Kubernetes/Openshift template repos with just reference to the operator? OpenShift repo is deprecated, and the Kubernetes repo strongly suggests using the operator.
We may also want to reference the helm chart at some point.
| A Kubernetes application is an app that is both deployed on Kubernetes and managed using the Kubernetes APIs and `kubectl` (kubernetes) or `oc` (OKD) tooling. To be able to make the most of Kubernetes, you need a set of cohesive APIs to extend in order to service and manage your apps that run on Kubernetes. Think of Operators as the runtime that manages this type of app on Kubernetes. | ||
|
|
||
|
|
||
| # Installing the Operator |
There was a problem hiding this comment.
Should we also have subsections for installing via operatorhub/OCP equivalent?
There was a problem hiding this comment.
Good question. Which utility would we use in the example (kubectl or oc)?
There was a problem hiding this comment.
No, as far as I know this would be UI driven.
| <10> Define annotations to be applied to all deployments (not services). These can be overridden by annotations defined on the individual components. | ||
|
|
||
|
|
||
| # Understanding Custom Resource Definitions |
There was a problem hiding this comment.
Just wondering whether this section should be before Creating a Simple Jaeger Instance?
There was a problem hiding this comment.
On second thoughts think it actually belongs in the first "Understanding Operators" second, as it is a general introduction to a Kubernetes capability that enables operators, and is nothing specific to Jaeger.
There was a problem hiding this comment.
IMO, the doc should begin with a quick-start, and then expand to explain everything else.
There was a problem hiding this comment.
I'll look at reorganizing things so that the doc starts with a quick-start.
|
|
||
| # Installing the Operator | ||
|
|
||
| IMPORTANT: The Jaeger Operator version is related to the version of the Jaeger components (Query, Collector, Agent) up to the minor portion. The patch version portion does *not* follow the ones from the Jaeger components. For instance, the Operator version 1.8.1 uses the Jaeger Docker images tagged with version 1.8 by default. |
There was a problem hiding this comment.
Markdown has no support for admonitions. We might need some other formatting here.
There was a problem hiding this comment.
I went with bold.
There was a problem hiding this comment.
I'll add some admonition capabilities. PR coming later today 👍
There was a problem hiding this comment.
@lucperkins I saw this right after I pushed an update. I'll take a look at #261 tomorrow. Thanks!
There was a problem hiding this comment.
I just merged the support for admonitions and added a couple of them in the performance tuning guide (not merged yet).
| You can view example custom resources for different Jaeger configurations [on GitHub](https://github.com/jaegertracing/jaeger-operator/tree/master/deploy/examples). | ||
|
|
||
| The simplest possible way to install is by creating a YAML file like the following: | ||
| <!-- TODO - Provide an overview of what we’re getting by default: one container, running what services? Just the server that serves up the console? Or is this the operator version of the All in one Executable? Which installs the Jaeger UI, collector, query, and agent, with an in memory storage component?--> |
There was a problem hiding this comment.
Or is this the operator version of the All in one Executable? Which installs the Jaeger UI, collector, query, and agent, with an in memory storage component?
That's exactly it. IIRC, Agents can still be injected as sidecars, though.
| <10> Define annotations to be applied to all deployments (not services). These can be overridden by annotations defined on the individual components. | ||
|
|
||
|
|
||
| # Understanding Custom Resource Definitions |
There was a problem hiding this comment.
IMO, the doc should begin with a quick-start, and then expand to explain everything else.
Signed-off-by: Julie Stickler <[email protected]>
|
|
||
| IMPORTANT: The Jaeger Operator version is related to the version of the Jaeger components (Query, Collector, Agent) up to the minor portion. The patch version portion does *not* follow the ones from the Jaeger components. For instance, the Operator version 1.8.1 uses the Jaeger Docker images tagged with version 1.8 by default. | ||
|
|
||
| NOTE: The following instructions will deploy a version of the operator that is using the latest `master` version. If you want to install a particular stable version of the operator, you will need to edit the `operator.yaml` file and specify the version as the tag in the container image and then use the approproiate `apiVersion` for the Jaeger operator. |
There was a problem hiding this comment.
This paragraph is no longer required - we switched back to using a tagged version but didn't update the readme.
|
|
||
|
|
||
|
|
||
| |Up to version |apiVersion |CRD yaml |
There was a problem hiding this comment.
@jpkrohling Should we have this table now? Unlikely anyone is using alpha.
We will need a way to identify different CRD as they change, but not sure for starting this documentation we currently need to refer to the alpha.
|
|
||
|
|
||
| ## Installing the Operator on Kubernetes | ||
|
|
There was a problem hiding this comment.
As I think we discussed already, would be good if we could use tabs to show differences between instructions, e.g. something like https://yassir.dev/markdown-fenced-code-tabs/.
@yurishkuro @lucperkins is this something that could be supported in the docs site?
There was a problem hiding this comment.
+1 this is a nice view. We could use the same to show different storage flags. Related comment is #257 (comment)
|
|
||
| <2> This installs the "Custom Resource Definition" for the `apiVersion: jaegertracing.io/v1` | ||
|
|
||
| IMPORTANT: When using a Jaeger Operator up to v1.10.0, install the CRD file `io_v1alpha1_jaeger_crd.yaml` in addition to `jaegertracing_v1_jaeger_crd.yaml`. This is because up to that version, the `apiVersion` in use was `io.jaegertracing/v1alpha1`. |
There was a problem hiding this comment.
If the table is removed above, then this para can also be deleted.
There was a problem hiding this comment.
I think we should remove mentions to the legacy CRD.
|
|
||
| <2> This installs the "Custom Resource Definition" for the `apiVersion: jaegertracing.io/v1` | ||
|
|
||
| IMPORTANT: When using a Jaeger Operator up to v1.10.0, install the CRD file `io_v1alpha1_jaeger_crd.yaml` in addition to `jaegertracing_v1_jaeger_crd.yaml`. This is because up to that version, the `apiVersion` in use was `io.jaegertracing/v1alpha1`. |
There was a problem hiding this comment.
Same point as above - depends on decision regarding referring to the alpha CRD.
|
|
||
| The `streaming` strategy is designed to augment the `production` strategy by providing a streaming capability that effectively sits between the collector and the backend storage (Cassandra or Elasticsearch). This provides the benefit of reducing the pressure on the backend storage, under high load situations, and enables other trace post-processing capabilities to tap into the real time span data directly from the streaming platform (Kafka). | ||
|
|
||
| The only additional information required is to provide the details for accessing the Kafka platform, which is configured in the `ingester` component: |
There was a problem hiding this comment.
"which is configured in the collector component (as producer) and ingester component (as consumer):"
- recent change, and the readme text wasn't updated, although the example snippet below was.
| The simplest possible way to install is by creating a YAML file like the following: | ||
| <!-- TODO - Provide an overview of what we’re getting by default: one container, running what services? Just the server that serves up the console? Or is this the operator version of the All in one Executable? Which installs the Jaeger UI, collector, query, and agent, with an in memory storage component?--> | ||
|
|
||
| .simplest.yaml |
There was a problem hiding this comment.
Is this required? Doesn't render correctly if intended to be a block title.
There was a problem hiding this comment.
In asciidoc, this renders the file name (simplest.yaml) somewhere around the code snippet. In Github, it appears without style at the top-left corner of the code.
In most cases of this doc, I think this can be removed.
|
|
||
| For reference, here's how you can create a more complex all-in-one instance: | ||
|
|
||
| .all-in-one.yaml |
| To uninstall the operator, run the following commands: | ||
|
|
||
|
|
||
| ```bash |
There was a problem hiding this comment.
We also need the openshift equivalent commands.
| A Kubernetes application is an app that is both deployed on Kubernetes and managed using the Kubernetes APIs and `kubectl` (kubernetes) or `oc` (OKD) tooling. To be able to make the most of Kubernetes, you need a set of cohesive APIs to extend in order to service and manage your apps that run on Kubernetes. Think of Operators as the runtime that manages this type of app on Kubernetes. | ||
|
|
||
|
|
||
| # Installing the Operator |
There was a problem hiding this comment.
No, as far as I know this would be UI driven.
|
@JStickler Could you also include the text recently added to the jaeger-operator readme in jaegertracing/jaeger-operator#346 ? |
Signed-off-by: Gary Brown <[email protected]>
Signed-off-by: Gary Brown <[email protected]>
| # Accessing the Jaeger Console (UI) | ||
| <!-- TODO Add tabs shortcode --> | ||
|
|
||
| {{< danger >}} |
There was a problem hiding this comment.
@jpkrohling Is this necessary? as k8s and ocp are dealt with in different sections?
There was a problem hiding this comment.
Let's remove it. If we think users are confused and expecting an ingress when a CR is installed on OpenShift, we can add it back.
| Under some circumstances, the Jaeger Operator can make use of the [Elasticsearch Operator](https://github.com/openshift/elasticsearch-operator) to provision a suitable Elasticsearch cluster. | ||
|
|
||
| {{< danger >}} | ||
| This feature is experimental and has been tested only on OpenShift clusters. Elasticsearch also requires the memory setting to be configured like `minishift ssh -- 'sudo sysctl -w vm.max_map_count=262144'`. Spark dependencies are not supported with this feature [Issue #294](https://github.com/jaegertracing/jaeger-operator/issues/294). |
There was a problem hiding this comment.
@jpkrohling Was thinking of removing the "experimental" part - but leave only tested on openshift? and change to warning.
There was a problem hiding this comment.
By the way, minishift is no more, but not sure what can be used instead...
There was a problem hiding this comment.
removed the minishift part as well for now.
| # Installing the Operator | ||
|
|
||
| {{< danger >}} | ||
| The Jaeger Operator version is related to the version of the Jaeger components (Query, Collector, Agent) up to the minor portion. The patch version portion does *not* follow the ones from the Jaeger components. For instance, the Operator version 1.8.1 uses the Jaeger Docker images tagged with version 1.8 by default. |
There was a problem hiding this comment.
@jpkrohling Is this para still relevant? If we change so the operator version and backend components are version aligned? So the jaeger.version file should have a major.minor.patch number?
There was a problem hiding this comment.
Not as danger, but as info, or warning? Or even as a regular paragraph. I think we should keep the message that each Jaeger Operator version tracks one Jaeger version.
Signed-off-by: Gary Brown <[email protected]>
objectiser
changed the title
| kubectl create -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/master/deploy/role_binding.yaml | ||
| kubectl create -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/master/deploy/operator.yaml | ||
| ``` | ||
| <1> This creates the namespace used by default in the deployment files. If you want to install the Jaeger operator in a different namespace, you must edit the deployment files to change `observability` to the desired namespace value. |
There was a problem hiding this comment.
In Asciidoc, this potentially renders nicely, like this:
As this is markdown, I think we should convert this <1> into an ordered list (and pay attention to the numbers listed in the code vs. numbers listed in the explanation)
|
|
||
| <!-- TODO: Add instructions for installing via the operatorhub? --> | ||
|
|
||
| The instructions from the previous section also work for installing the operator on OKD or OpenShift. Make sure you are logged in as a privileged user, such as `system:admin`, when you install the role based acces control (RBAC) rules, the custom resource definition, and the operator. |
There was a problem hiding this comment.
At least for CRC, the privileged user is now "kubeadmin". Not sure there's even a "system:admin" anymore.
| oc create -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/master/deploy/role_binding.yaml | ||
| oc create -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/master/deploy/operator.yaml | ||
| ``` | ||
| <1> This creates the namespace used by default in the deployment files. If you want to install the Jaeger operator in a different namespace, you must edit the deployment files to change `observability` to the desired namespace value. |
There was a problem hiding this comment.
Same as previous: ordered list here.
| oc adm policy add-scc-to-user daemonset-with-hostport -z jaeger-agent-daemonset # <3> | ||
| oc apply -f https://raw.githubusercontent.com/jaegertracing/jaeger-operator/master/deploy/examples/openshift/agent-as-daemonset.yaml # <4> | ||
| ``` | ||
| <1> The `SecurityContextConstraints` with the `allowHostPorts` policy |
| In a few seconds, a new in-memory all-in-one instance of Jaeger will be available, suitable for quick demos and development purposes. To check the instances that were created, list the `jaeger` objects: | ||
|
|
||
| ```bash | ||
| $ kubectl get jaeger |
There was a problem hiding this comment.
I think it's common to issue the get commands using the object in plural: kubectl get jaegers
| The default create-schema job uses `MODE=prod`, which implies a replication factor of `2`, using `NetworkTopologyStrategy` as the class, effectively meaning that at least 3 nodes are required in the Cassandra cluster. If a `SimpleStrategy` is desired, set the mode to `test`, which then sets the replication factor of `1`. Refer to the [create-schema script](https://github.com/jaegertracing/jaeger/blob/master/plugin/storage/cassandra/schema/create.sh) for more details. | ||
| {{< /info >}} | ||
|
|
||
| ### Elasticesearch storage |
There was a problem hiding this comment.
s/Elasticesearch/Elasticsearch
|
|
||
| ## OpenShift | ||
|
|
||
| When using the `operator-openshift.yaml` resource, the Operator will automatically create a `Route` object for the query services. Use the following command to check the hostname/port: |
There was a problem hiding this comment.
This doesn't exist anymore. "When the operator is running on OpenShift, ..." would be more appropriate.
| Make sure to use `https` with the hostname/port you get from the command above, otherwise you'll see a message like: "Application is not available". | ||
| {{< /info >}} | ||
|
|
||
| By default, the Jaeger UI is protected with OpenShift's OAuth service and any valid user is able to login. For development purposes, the user/password combination `developer/developer` can be used. To disable this feature and leave the Jaeger UI unsecured, set the Ingress property `security` to `none` in the custom resource file: |
There was a problem hiding this comment.
developer/developer doesn't work anymore with CRC. It's kubeadmin, with the password shown when the cluster was created.
There was a problem hiding this comment.
I would remove the entire phrase, as the previous one says it all: "any valid user is able to login".
Signed-off-by: Gary Brown <[email protected]>
Which problem is this PR solving?
The Jaeger operator is documented in a README on the repo, but not on jaegertracing.io.
Short description of the changes
Adapted the content from the Jaeger operator repo for the documentation on the web site.
@objectiser @jpkrohling @pavolloffay, here's a first pass at adapting the content. I've got several TODO's marked in the file where we still need content or updates.