Doc restructuring (#196)

Co-authored-by: Ori Shoshan <[email protected]>

.gitignore

@@ -21,3 +21,4 @@ yarn-error.log*
 
 .idea
 package-lock.json
+.vercel

docs/features/README.mdx

@@ -0,0 +1,54 @@
+---
+sidebar_position: 1
+title: Features
+hide_title: true
+---
+
+
+import {
+    useCurrentSidebarCategory
+} from '@docusaurus/theme-common';
+
+
+
+export default function FeatureCards() {
+    const category = useCurrentSidebarCategory();
+    const features = category.items;
+    console.log(JSON.stringify(features));
+    return (
+        <div className="tw-m-8">
+            <h1 className="tw-text-2xl tw-font-medium">Features</h1>
+            <p className="tw-">
+                Otterize makes it easy to create and visualize authorization for your Kubernetes clusters across a
+                variety of
+                services. Explore each below.
+            </p>
+            <div role="list" className="tw-grid tw-gap-6 tw-grid-cols-3">
+                {features.map((feature) => (
+                    <div key={feature.label}
+                         className="tw-col-span-1 tw-flex tw-flex-col tw-divide-y tw-divide-gray-200 tw-rounded-lg tw-border tw-border-solid tw-border-primary-500 tw-bg-white tw-text-center tw-border-1 tw-border-primary-400 tw-border-solid hover:tw-border-primary-600 hover:tw-shadow-md">
+                            <a href={feature.href} className="hover:tw-no-underline hover:tw-font-extrabold">
+                                <div className="tw-flex tw-flex-1 tw-flex-col tw-p-8">
+                                    <div
+                                        className=" tw-flex tw-max-h-16 tw-h-16 tw-w-full text-center tw-justify-center ">
+                                        {feature.customProps && feature.customProps.image &&
+                                            <img className="justify-self-center tw-max-h-16"
+                                                 src={feature.customProps.image}
+                                                 alt=""/>
+                                        }
+                                    </div>
+                                    <h3 className="tw-mt-6 tw-text-lg tw-font-semibold tw-text-gray-black">{feature.label}</h3>
+                                </div>
+                            </a>
+                    </div>
+                ))}
+            </div>
+        </div>
+    )
+}
+
+
+
+
+
+

docs/features/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Features",
+  "position": 3,
+  "collapsed": false,
+  "customProps": {
+    "image": "/img/icons/aws.png"
+  }
+}

docs/features/aws-iam/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "AWS IAM",
+  "position": 2,
+  "collapsed": true,
+  "customProps": {
+    "image": "/img/icons/aws.png"
+  }
+}

docs/features/aws-iam/index.mdx

@@ -0,0 +1,59 @@
+---
+sidebar_position: 1
+title: AWS IAM | Overview
+hide_table_of_contents: true
+hide_title: true
+---
+
+import DocsLinkCard from "@site/src/components/LinkCard";
+
+export const tutorials = [
+    {
+        title: 'Automate AWS IAM for EKS',
+        description: 'Create just-in-time AWS IAM roles and policies that are kept in sync with your workloads',
+        url: 'aws-iam/tutorials/aws-iam-eks'
+    },
+];
+
+
+# AWS IAM
+
+Otterize can create just-in-time AWS IAM roles and policies for your workloads running on EKS Kubernetes clusters, greatly simplifying the lifecycle of managing IAM roles and policies.
+
+### Tutorials
+
+To learn how to use the Intents Operator and Credentials Operator to manage just-in-time AWS IAM access, check out the tutorial.
+<DocsLinkCard items={tutorials} colSize={"sm"}/>
+
+
+### How does Otterize work with AWS IAM?
+
+1. First, the EKS cluster must have [Otterize installed](/overview/installation).
+2. To have a role created for a pod, label the pod with `credentials-operator.otterize.com/create-aws-role: "true"`
+3. The credentials operator will create a role and an `AssumeRolePolicy` (trust relationship) bound to the pod's ServiceAccount. The ServiceAccount will be annotated automatically.
+4. At this point, the pod is able to assume the role, but role does not have the ability to perform any actions. We will need to create a ClientIntents YAML for the access the service requires and apply it to our cluster. Below is an example of a ClientIntents file for accessing an S3 bucket. View the [reference](/features/aws-iam/reference) to learn more about the AWS IAM ClientIntents syntax.
+5. Once the intent is applied, the intents operator will create a new policy, which will be attached to the service’s role with the appropriate access.
+6. Done!
+
+```yaml
+apiVersion: k8s.otterize.com/v1alpha3
+kind: ClientIntents
+metadata:
+  name: server
+spec:
+  service:
+    name: server
+  calls:
+    - name: arn:aws:s3:::example-bucket-*/*
+      type: aws
+      awsActions:
+        - "s3:PutObject"
+        - "s3:GetObject"
+```
+
+### Automatically generating ClientIntents for AWS IAM
+
+Figuring out which access you need for AWS can be a painful, trial and error process, and something you _must_ do if you're tightening production access.
+
+Otterize is getting ready to release support for using existing traffic to generate least-privilege IAM policies. Keen to try this out as part of early access? Sign up to the [Early Access Beta Program](https://otterize.com/EarlyAccessBetaProgram) and we'll be in touch!
+

docs/features/aws-iam/reference.mdx

@@ -0,0 +1,47 @@
+---
+sidebar_position: 3
+title: Reference
+---
+
+### ClientIntents example (YAML)
+
+```yaml
+apiVersion: k8s.otterize.com/v1alpha3
+kind: ClientIntents
+metadata:
+  name: server
+spec:
+  service:
+    # The name of the pod that will be granted access
+    name: server
+  calls:
+      # The AWS ARN or ARN wildcard that references the resource(s) for the authorization
+    - name: arn:aws:s3:::example-bucket-*/*
+      type: aws
+      # one or more AWS Actions or Action wildcards that will be provided to the specified resources
+      awsActions:
+        - "s3:PutObject"
+        - "s3:GetObject"
+      # Multiple call definitions can be defined for a single service.
+	- name: arn:aws:s3:::read-only-bucket-*/*
+      type: aws
+      awsActions:
+        - "s3:GetObject"
+```
+
+### Annotations
+
+| Key                                                        | Description                                                                                                                                                                                  | Default  |
+|------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
+| `credentials-operator.otterize.com/create-aws-role` | By setting to **true** the credential operator will create an unique AWS Role for the associated pod | `false` |
+
+
+### Helm Chart options
+
+| Key                                                        | Description                                                                                                                                                                                  | Default  |
+|------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
+| `global.aws.enabled`                                       | Enable or disable AWS integration                                                                                                                                                            | `false`  |
+| `global.aws.eksClusterNameOverride`                        | EKS cluster name (overrides auto-detection)                                                                                                                                                  | `(none)` |
+| `aws.roleARN` | ARN of the AWS role the operator will use to access AWS. By defeault, Otterize will create a unique role for each service an annotate the service with the role's ARN. | `(none)` |
+
+View the [Helm chart reference](/reference/configuration/otterize-chart) for all other options

docs/quickstart/visualization/_category_.json → docs/features/aws-iam/tutorials/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "Visualization",
+  "label": "Tutorials",
   "position": 2,
   "collapsed": false
 }

docs/quickstart/access-control/aws-iam-eks.mdx → docs/features/aws-iam/tutorials/aws-iam-eks.mdx

@@ -18,7 +18,7 @@ In this tutorial, we will:
 ## Prerequisites
 Already have Otterize deployed with the IAM integration configured on your cluster? [Skip to the tutorial.](#tutorial)
 
-#### 1. Create an AWS EKS cluster
+### 1. Create an AWS EKS cluster
 Before you start, you'll need an AWS EKS cluster. Any cluster will do; there are no special requirements or setup.
 
 <details>
@@ -83,7 +83,7 @@ Don't forget to configure your kubeconfig for your cluster. If using the example
 aws eks update-kubeconfig --region us-west-2 --name otterize-iam-eks-tutorial
 ```
 
-#### 2. Deploy Otterize for AWS IAM
+### 2. Deploy Otterize for AWS IAM
 To deploy Otterize, head over to [Otterize Cloud](https://app.otterize.com) and:
 
 1. Create a Kubernetes cluster on the [Integrations page](https://app.otterize.com/integrations), and follow the instructions. *Make sure to enable enforcement mode for this tutorial.* If you already have a Kubernetes cluster connected, skip this step.
@@ -185,7 +185,7 @@ kubectl patch deployment -n otterize-tutorial-iam server --type='json' -p="[{\"o
 <summary>Expand to see the deployment YAML</summary>
 
 ```yaml
-{@include: ../../../static/code-examples/aws-iam-eks/client-and-server.yaml}
+{@include: ../../../../static/code-examples/aws-iam-eks/client-and-server.yaml}
 ```
 
 </details>
@@ -285,7 +285,7 @@ By annotating the pod, we've created an IAM role. We now need to specify what we
 
 We will specify the following ClientIntents, granting the PutObject permission to the `otterize-tutorial-bucket` S3 bucket.
 ```yaml
-{@include: ../../../static/code-examples/aws-iam-eks/clientintents.yaml}
+{@include: ../../../../static/code-examples/aws-iam-eks/clientintents.yaml}
 ```
 
 To apply these intents, run the following command:
@@ -322,7 +322,7 @@ aws s3 ls $BUCKET_NAME
 2023-11-17 20:42:55         19 testfile.3.txt
 ```
 
-## What's next?
+### What's next?
 
 Try out some of the other quick tutorials to learn about how to use ClientIntents to manage network policies, Istio policies, PostgreSQL access, and more. You can use a single ClientIntents resource to specify all the access required for a pod.
 

docs/features/istio/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Istio",
+  "position": 4,
+  "collapsed": true,
+  "customProps": {
+    "image": "/img/icons/istio-no-word-mark.svg"
+  }
+}

docs/features/istio/index.mdx

@@ -0,0 +1,96 @@
+---
+sidebar_position: 1
+title: Istio | Overview
+hide_title: true
+---
+
+import DocsLinkCard from "@site/src/components/LinkCard";
+
+export const istio_tutorials = [
+    {
+        title: 'Istio AuthorizationPolicy automation',
+        description: 'Generate AuthorizationPolicy docs from existing connections',
+        url: 'istio/tutorials/k8s-istio-authorization-policies'
+    },
+    {
+        title: 'Istio HTTP-level access mapping',
+        description: 'Map access between services including HTTP paths and methods',
+        url: 'istio/tutorials/k8s-istio-watcher'
+    }
+];
+
+
+
+# Istio
+
+Otterize can build a map of your cluster based on Istio Envoy metrics, and enforce access between services using Istio Authorization Policies.
+
+### Tutorials
+
+To learn how to use the Intents Operator to enforce access using Istio authorization policies, or map your cluster, try one of these quickstart tutorials.
+
+<DocsLinkCard items={istio_tutorials} colSize={"sm"}/>
+
+
+### How does Otterize work with Istio?
+
+1. First, the cluster must have [Otterize installed](/overview/installation).
+2. To have Otterize generate Istio authorization policies, declare and apply ([IBAC](/overview/intent-based-access-control)) ClientIntents for your services.
+Once you do so, Otterize will generate an Istio authorization policy allowing access from the client service, identified by its ServiceAccount, to the server, identified by its labels.
+The HTTP Resources section in the ClientIntents is optional: if you do not specify it, all pod-to-pod access is allowed.
+
+```yaml
+
+apiVersion: k8s.otterize.com/v1alpha3
+kind: ClientIntents
+metadata:
+  name: client
+  namespace: otterize-tutorial-istio
+spec:
+  service:
+    name: client
+  calls:
+    - name: server-abc
+      type: http
+      HTTPResources:
+        - path: /client-path
+          methods: [ GET ]
+
+```
+
+3. If you would like Otterize to be able to autogenerate ClientIntents and map your network at the HTTP path and method level, we need to enable connection telemetry data within Istio. This can be enabled with the following YAML:
+
+```yaml
+apiVersion: telemetry.istio.io/v1alpha1
+kind: Telemetry
+metadata:
+  name: mesh-default
+  namespace: istio-system
+spec:
+  # Configure access logging for Istio services
+  accessLogging:
+    # Define the access logging provider, in this case, Envoy
+    - providers:
+        - name: envoy
+  metrics:
+    # Configure metrics collection for Istio services using Prometheus
+    - providers:
+        - name: prometheus
+      # Customize metric tag overrides
+      overrides:
+        - tagOverrides:
+            # Map the "request_method" metric tag to "request.method" value
+            request_method:
+              value: request.method
+            # Map the "request_path" metric tag to "request.path" value
+            request_path:
+              value: request.path
+```
+
+Or, as a ready-to-paste command:
+```
+kubectl apply -f ${ABSOLUTE_URL}/code-examples/network-mapper/istio-telemetry-enablement.yaml -n istio-system
+```
+
+Once installed, Otterize will query Envoy sidecars for known connections and build an in-memory map of the relationships. After the map is built you can then view those relationships.
+

docs/features/istio/reference.mdx

@@ -0,0 +1,38 @@
+---
+sidebar_position: 3
+title: Reference
+---
+
+### ClientIntents example (YAML)
+
+```yaml
+apiVersion: k8s.otterize.com/v1alpha3
+kind: ClientIntents
+metadata:
+  name: client
+  namespace: otterize-tutorial-istio
+spec:
+  service:
+    name: client
+  calls:
+    - name: nginx
+      type: http
+      HTTPResources:
+        - path: /client-path
+          methods: [ GET ]
+```
+
+
+### Helm Chart options
+
+| Key                             | Description                             | Default                        |
+|---------------------------------|-----------------------------------------|--------------------------------|
+| `istiowatcher.enable`           | Enable Istio watcher deployment (beta). | `false`                        |
+| `istiowatcher.image.repository` | Istio watcher image repository.         | `otterize`                     |
+| `istiowatcher.image.image`      | Istio watcher image.                    | `network-mapper-istio-watcher` |
+| `istiowatcher.image.tag`        | Istio watcher image tag.                | `latest`                       |
+| `istiowatcher.pullPolicy`       | Istio watcher pull policy.              | `(none)`                       |
+| `istiowatcher.pullSecrets`      | Istio watcher pull secrets.             | `(none)`                       |
+| `istiowatcher.resources`        | Resources override.                     | `(none)`                       |
+
+View the [Helm chart reference](/reference/configuration/otterize-chart) for all other options

docs/features/istio/tutorials/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Tutorials",
+  "position": 2,
+  "collapsed": false
+}