Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Usage metrics documentation #77

Merged
merged 6 commits into from
May 4, 2023
Merged

Usage metrics documentation #77

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
34d8504
Documenting the telemetry capability of Otterize OSS.
usarid Apr 29, 2023
c80120f
enable -> enabled
omris94 Apr 30, 2023
bc16247
Updating the docs per the latest schema of telemetry metrics.
usarid May 3, 2023
4e89898
pluralize
omris94 May 3, 2023
49bbce8
Update usage-telemetry.mdx
orishoshan May 3, 2023
ba208bd
add helm chart values
omris94 May 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
15 changes: 13 additions & 2 deletions docs/otterize-oss/README.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,10 @@ Otterize OSS implements intent-based access control (IBAC) in a single Kubernete
It is a fully standalone, free and open-source software implementation of IBAC built for cloud-native
teams that use Kubernetes at the core of their infrastructure.

It consists of several components:
## Components

Otterize OSS consists of several components, which work together to provide IBAC capabilities.

- The [Otterize intents operator](/reference/configuration/intents-operator) that translates ClientIntents resources to
access controls using plugins, which currently include:
- A network policies manager to control pod-to-pod access.
Expand All @@ -17,9 +20,17 @@ to handle pod identities and manage certificates.
- The [Otterize network mapper](/reference/configuration/network-mapper) that sniffs pod-to-pod traffic and builds a network map,
which is useful on its own and may also be exported as client intents files for bootstrapping IBAC.

This list will grow over time, as more capabilities are added, in particular support for more access controls, credentials managers, and integrations with useful tooling.

The Otterize OSS code base and issues are managed [on GitHub](https://github.com/otterize).

To get started with Otterize OSS, see the tutorials for [network policies](/quick-tutorials/k8s-network-policies), [Kafka](/quick-tutorials/k8s-kafka-mtls), [network mapping](/quick-tutorials/k8s-network-mapper), and [mTLS](/quick-tutorials/k8s-mtls).
To get started with Otterize OSS, see the tutorials for [network policies](/quick-tutorials/k8s-network-policies), [Kafka](/quick-tutorials/k8s-kafka-mtls), [network mapping](/quick-tutorials/k8s-network-mapper), and [Istio service mesh](/quick-tutorials/k8s-istio-authorization-policies).

## Usage metrics

Components in Otterize OSS collect usage information — counts of events like `INTENTS_APPLIED`, `NETWORK_POLICY_CREATED`, `KAFKA_ACL_DELETED`, etc. — and can report those back to the Otterize team. This is entirely optional and does not affect the functionality of Otterize OSS, but it does help the team at Otterize understand what the community finds useful and hence how to improve it. (Of course, direct feedback through the [Otterize Community Slack](https://joinslack.otterize.com/) is very much appreciated too.) For more information, including what is sent and how to turn it off or on, see [the usage telemetry documentation](/otterize-oss/usage-telemetry).

## Roadmap

The near-term roadmap for Otterize OSS currently includes:
- [[Done](https://github.com/otterize/otterize-cli/releases/tag/v0.1.17)] Adding **network map visualization** capabilities to the Otterize CLI, so you can get network map images from the network mapper.
Expand Down
4 changes: 4 additions & 0 deletions docs/otterize-oss/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"position": 7,
"collapsed": true
}
54 changes: 54 additions & 0 deletions docs/otterize-oss/usage-telemetry.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
---
title: Usage telemetry
---

Operators in Otterize OSS report anonymous usage information back to the Otterize team, to help the team understand how the software is used in the community and what aspects users find useful. No personal or organizational identifying information is transmitted in these metrics: they only reflect patterns of usage. You may opt out at any time through a single configuration flag.

## What information is collected?

The information reported by Otterize OSS is defined in the [GraphQL schema of the telemetry source code](https://github.com/otterize/intents-operator/blob/main/src/shared/telemetries/telemetriesgql/schema.graphql); this is the GraphQL schema shared with the Otterize incoming-telemetry GraphQL endpoint. Usage information is sent as events, each containing the event type, sometimes also a count, and some identifiers to allow correlating multiple events in order to understand usage.

### Identifiers

| Identifier | Value |
|:----------------------|:-------------------------------------------------------------------------------------------------------------------------------------|
| `componentType` | Which Otterize OSS component sent the event: one of `INTENTS_OPERATOR`, `CREDENTIALS_OPERATOR`, `NETWORK_MAPPER` or `CLI`. |
| `componentInstanceId` | A randomly-generated UUID identifying the installed instance of the component, to allow correlating its events. |
| `contextId` | A hash (for anonymity) of an identifier of the context in which the component is installed. For example, for components running in a Kubernetes cluster, this is a hash of the UUID of the `kube-system` namespace in the cluster. |
| `version` | The version of the Otterize OSS component. |
| `cloudClientId` | If connected to Otterize Cloud: the client id used to connect with Otterize Cloud, to allow correlating events with Cloud usage info. |

### Events

| Event type | Meaning |
|:----------------------------------|:-----------------------------------------------------------------------------------------------------|
| `INTENTS_DELETED` | How many intents were deleted. |
| `INTENTS_APPLIED` | How many declared intents were applied. |
| `INTENTS_DISCOVERED` | How many intents were discovered by the network mapper. |
| `INTENTS_DISCOVERED_SOCKET_SCAN` | How many intents were discovered by the network watcher ("sniffer") via scanning for open sockets. |
| `INTENTS_DISCOVERED_DNS` | How many intents were discovered by the network watcher ("sniffer") via reading DNS query responses. |
| `INTENTS_DISCOVERED_KAFKA` | How many intents were discovered by the Kafka watcher. |
| `INTENTS_DISCOVERED_ISTIO` | How many intents were discovered by the Istio watcher. |
| `MAPPER_EXPORT ` | How many intents from the network mapper were exported by the CLI: `otterize mapper export...`. |
| `MAPPER_VISUALIZE` | How many intents from the network mapper were visualized by the CLI: `otterize mapper visualize...`. |
| `KAFKA_SERVER_CONFIG_APPLIED` | A Kafka Server Config was applied (i.e. the intents operator will recognize it as a Kafka broker). |
| `KAFKA_SERVER_CONFIG_DELETED` | A Kafka Server Config was deleted. |
| `NETWORK_POLICIES_CREATED` | How many network policies were created by the intents operator. |
| `NETWORK_POLICIES_DELETED` | How many network policies were deleted by the intents operator. |
| `KAFKA_ACLS_CREATED` | How many Kafka ACLs were created by the intents operator. |
| `KAFKA_ACLS_DELETED` | How many Kafka ACLs were deleted by the intents operator. |
| `ISTIO_POLICIES_CREATED` | How many Istio authorization policies were created by the intents operator. |
| `ISTIO_POLICIES_DELETED` | How many Istio authorization policies were deleted by the intents operator. |
| `STARTED` | The operator was started. |

## Configuring whether to report usage information

To configure whether to report usage information to the Otterize team, use the `telemetry` flag in the installation/configuration of Otterize OSS. By default, telemetry is enabled.

To **disable** sending usage information:
- Via the Otterize OSS Helm chart: `--set global.telemetry.enabled=false`.
- Via an environment variable: `OTTERIZE_TELEMETRY_ENABLED=false`.
- If running an operator directly: `telemetry-enabled=false`.

If the `telemetry` flag is omitted or set to `true`, telemetry will be enabled: usage information will be reported.

14 changes: 8 additions & 6 deletions docs/reference/configuration/intents-operator/helm-chart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,17 +18,19 @@ If you would like to deploy it on its own, add the Otterize Helm chart repositor

## Global parameters
| Key | Description | Default |
|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|---------|
|:---------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------|---------|
| `global.allowGetAllResources` | If defined overrides `allowGetAllResources`. | |
| `global.telemetry.enabled` | If set to `false`, anonymous telemetries collection will be disabled | `true` |


## Operator parameters
| Key | Description | Default |
|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------|
|:-------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------|
| `operator.image.repository` | intents operator image repository. | `otterize` |
| `operator.image.image` | intents operator image. | `intents-operator` |
| `operator.image.tag` | intents operator image tag. | `latest` |
| `operator.pullPolicy` | intents operator image pull policy. | `(none)` |
| `operator.autoGenerateTLSUsingCredentialsOperator` | If set to true, adds the necessary pod annotations in order to integrate with credentials-operator, and get tls certificate. | `false` |
| `operator.autoGenerateTLSUsingCredentialsOperator` | If set to true, adds the necessary pod annotations in order to integrate with credentials-operator, and get tls certificate. | `false` |
| `operator.enableEnforcement` | If set to false, enforcement is disabled globally (both for network policies and Kafka ACL). If true, you may use the other flags for more granular enforcement settings | `true` |
| `operator.enableNetworkPolicyCreation` | Whether the operator should create network policies according to ClientIntents | `true` |
| `operator.enableKafkaACLCreation` | Whether the operator should create Kafka ACL rules according to ClientIntents of type Kafka | `true` |
Expand All @@ -37,7 +39,7 @@ If you would like to deploy it on its own, add the Otterize Helm chart repositor

## Watcher parameters
| Key | Description | Default |
|----------------------------|----------------------------|--------------------------------|
|:---------------------------|:---------------------------|:-------------------------------|
| `watcher.image.repository` | Watcher image repository. | `otterize` |
| `watcher.image.image` | Watcher image. | `intents-operator-pod-watcher` |
| `watcher.image.tag` | Watcher image tag. | `latest` |
Expand All @@ -46,13 +48,13 @@ If you would like to deploy it on its own, add the Otterize Helm chart repositor

## Cloud parameters
| Key | Description | Default |
|-------------------------------------------------|-------------------------------------------------|----------|
|:------------------------------------------------|:------------------------------------------------|:---------|
| `global.otterizeCloud.credentials.clientId` | Client ID for connecting to Otterize Cloud. | `(none)` |
| `global.otterizeCloud.credentials.clientSecret` | Client secret for connecting to Otterize Cloud. | `(none)` |
| `global.otterizeCloud.apiAddress` | Overrides Otterize Cloud default API address. | `(none)` |
| `global.otterizeCloud.apiExtraCAPEMSecret` | The name of a secret containing a single `CA.pem` file for an extra root CA used to connect to Otterize Cloud. The secret should be placed in the same namespace as the Otterize deployment. | `(none)` |

## Common parameters
| Key | Description | Default |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
|:-----------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|
| `allowGetAllResources` | Gives get, list and watch permission to watch on all resources. This is used to resolve service names when pods have owners that are custom resources. When disabled, a limited set of permissions is used that only allows access to built-in Kubernetes resources that deploy Pods and Pods themselves - Deployments, StatefulSets, DaemonSets, ReplicaSets and Services. Resolving may not be able to complete if the owning resource is not one of those. | `true` |
2 changes: 2 additions & 0 deletions docs/reference/configuration/network-mapper/helm-chart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,8 @@ Checkout the network mapper [tutorial](/quick-tutorials/k8s-network-mapper) to s
| Key | Description | Default |
|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|---------|
| `global.allowGetAllResources` | If defined overrides `allowGetAllResources`. | |
| `global.telemetry.enabled` | If set to `false`, anonymous telemetries collection will be disabled | `true` |


## Common parameters
| Key | Description | Default |
Expand Down