diff --git a/docs/features/mysql/_category_.json b/docs/features/mysql/_category_.json new file mode 100644 index 000000000..dc681e687 --- /dev/null +++ b/docs/features/mysql/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "MySQL", + "position": 5, + "collapsed": true, + "customProps": { + "image": "/img/icons/mysql.svg" + } +} diff --git a/docs/features/mysql/index.mdx b/docs/features/mysql/index.mdx new file mode 100644 index 000000000..d39cf0b85 --- /dev/null +++ b/docs/features/mysql/index.mdx @@ -0,0 +1,111 @@ +--- +sidebar_position: 1 +title: MySQL | Overview +hide_title: true +--- + +import DocsLinkCard from "@site/src/components/LinkCard"; + +export const mysql_tutorials = [ + { + title: 'Just-in-time MySQL Access', + description: 'Learn how to manage just-in-time users and SQL GRANTs', + url: '/features/mysql/tutorials/mysql' + }, +]; + +# MySQL + +Otterize is able to create just-in-time username-and-password pairs for your service, providing them as a Kubernetes Secret that can be mounted to file or mapped to environment variables, as well as `GRANT`ing access to databases and tables, based on `ClientIntents` ([Intents-Based Access Control](/overview/intent-based-access-control)) declarations. + +### Tutorials + +To learn how to use the Intents Operator and Credentials Operator to enforce access using MySQL GRANTs, try one of these quickstart tutorials: + + + + + +### How does Otterize work with MySQL? + +The Otterize credentials operator will create a unique MySQL username-password combination for each service's use, exposed via a Kubernetes Secret. The service will use these credentials to connect to the database. `ClientIntents` will define the access required by that service. As the intents are applied, The Otterize intents operator will keep the database's list of users and GRANTs up to date so that the service is able to access it. + +1. To get started, your cluster must have Otterize deployed. +2. You'll need to create a `MySQLServerConfig` in your cluster, providing a connection URL and admin-level credentials for Otterize to manage permissions in your database. Below is an example `MySQLServerConfig` resource. +```yaml +apiVersion: k8s.otterize.com/v1alpha3 +kind: MySQLServerConfig +metadata: + name: mysql-tutorial-db # database instance name - should match the target in ClientIntents +spec: + address: # Your MySQL servers address + credentials: + username: # Username Otterize will connect with & configure permissions as + password: # Password for above username +``` + +3. Each service can request a username-password Secret to be created, by annotating the Pod with `credentials-operator.otterize.com/user-password-secret-name`. Below is an example of that annotation and passing the generated credentials into a container with environmental variables. + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: server +spec: + replicas: 1 + selector: + matchLabels: + app: server + template: + metadata: + annotations: + # highlight-next-line + credentials-operator.otterize.com/user-password-secret-name: server-creds + labels: + app: server + spec: + serviceAccountName: server + containers: + - name: server + imagePullPolicy: Always + image: 'supercool/my-example-container' + ports: + - containerPort: 80 + env: + - name: DB_SERVER_USER + valueFrom: + secretKeyRef: + name: server-creds + key: username + - name: DB_SERVER_PASSWORD + valueFrom: + secretKeyRef: + name: server-creds + key: password +``` + + +4. Apply `ClientIntents` and the specified access will be `GRANT`ed to the service in the `ClientIntents`. + + +```yaml +apiVersion: k8s.otterize.com/v1alpha3 +kind: ClientIntents +metadata: + name: client-intents-for-server + namespace: otterize-tutorial-mysql +spec: + service: + name: server + calls: + - name: mysql-tutorial-db # Same name as MySQLServerConfig metadata.name + type: database + databaseResources: + - databaseName: otterize-tutorial + table: example + operations: + - SELECT + - INSERT +``` + +5. Done! \ No newline at end of file diff --git a/docs/features/mysql/reference.mdx b/docs/features/mysql/reference.mdx new file mode 100644 index 000000000..db41196e6 --- /dev/null +++ b/docs/features/mysql/reference.mdx @@ -0,0 +1,45 @@ +--- +sidebar_position: 3 +title: Reference +--- + +### MySQLServerConfig example (YAML) +```yaml +apiVersion: k8s.otterize.com/v1alpha3 +kind: MySQLServerConfig +metadata: + name: mysql-tutorial-db # database instance name - should match the target in ClientIntents +spec: + address: # Your MySQL servers address + credentials: + username: # Username Otterize will connect with & configure permissions as + password: # Password for above username +``` + +### ClientIntents example (YAML) + +```yaml +apiVersion: k8s.otterize.com/v1alpha3 +kind: ClientIntents +metadata: + name: client-intents-for-server + namespace: otterize-tutorial-mysql +spec: + service: + # Service requiring access to MySQL + name: server + calls: + # This name will need to match the MySQLServerConfig metadata.name field + - name: otterize-tutorial-mysql + type: database + databaseResources: + - databaseName: otterize-tutorial + # Optional table name, if omitted all tables will be granted access + table: public.example + # Operations being granted, options include SELECT, INSERT, UPDATE, DELETE, ALL + operations: + - SELECT + - INSERT +``` + + diff --git a/docs/features/mysql/tutorials/_category_.json b/docs/features/mysql/tutorials/_category_.json new file mode 100644 index 000000000..bdfe77bf2 --- /dev/null +++ b/docs/features/mysql/tutorials/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Tutorials", + "position": 2, + "collapsed": false +} diff --git a/docs/features/mysql/tutorials/mysql.mdx b/docs/features/mysql/tutorials/mysql.mdx new file mode 100644 index 000000000..82cfb1c6b --- /dev/null +++ b/docs/features/mysql/tutorials/mysql.mdx @@ -0,0 +1,198 @@ +--- +sidebar_position: 2 +title: Just-in-time MySQL access +image: /img/quick-tutorials/mysql/social.png +--- + +import CodeBlock from "@theme/CodeBlock"; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +export const Terminal = ({children}) => ( +
+ {children} +
+); + + +# Overview +This tutorial will deploy an example cluster to highlight Otterize's MySQL capabilities. Within that cluster is a client service that hits an endpoint on a server, which then connects to a database. The server runs two different database operations: +1. An `INSERT` operation to append a table within the database +2. A `SELECT` operation to validate the updates. + +The server needs appropriate permissions to access the database. You could use one admin user for all services, which is insecure and is the cause for many security breaches. With Otterize, you can specify required access, and have Otterize create users and perform correctly scoped SQL GRANTs just in time, as the service spins up and down. + +In this tutorial, we will: +* Optionally, spin up a MySQL database instance, based on Amazon RDS for MySQL. Alternatively, you could use any MySQL server of your choice. +* Deploy an example cluster +* Deploy Otterize in our cluster and give it access to our database instance +* Declare a ClientIntents resource for the server, specifying required access +* See that the required access has been granted + +# Prerequisites + +#### 1. Minikube Cluster +
+ Prepare a Kubernetes cluster with Minikube + +For this tutorial you'll need a local Kubernetes cluster. Having a cluster with a [CNI](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) that supports [NetworkPolicies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) isn't required for this tutorial, but is recommended so that your cluster works with other tutorials. + +If you don't have the Minikube CLI, first [install it](https://minikube.sigs.k8s.io/docs/start/). + +Then start your Minikube cluster with Calico, in order to enforce network policies. + +```shell +minikube start --cpus=4 --memory 4096 --disk-size 32g --cni=calico +``` +
+ +#### 2. Deploy Otterize +To deploy Otterize, head over to [Otterize Cloud](https://app.otterize.com) and associate a Kubernetes cluster on the [Integrations page](https://app.otterize.com/integrations), and follow the instructions. If you already have a Kubernetes cluster connected, skip this step. + +#### 3. Deploy a MySQL database instance +Already have a MySQL database instance? [Skip to the tutorial.](#tutorial) + +
+Deploy a MySQL database instance, based on Amazon RDS for MySQL + +Follow the [installation instructions on the AWS RDS documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_GettingStarted.CreatingConnecting.MySQL.html#CHAP_GettingStarted.Creating.MySQL). + +
  • + You may use the Free tier template for this tutorial. +
    • +
  • + Under "Settings", choose "Auto generate password". Make sure you save the generated password after the instance is created. +
    • +
  • + Under "Connectivity", enable public access to allow access from your Kubernetes cluster. Otterize will require that access to manage credentials for you. + Additionally, make sure you choose a security group that allows inbound access from your Kubernetes cluster. + + Alternatively, if your Kubernetes cluster is running on AWS EKS, you may configure your RDS instance to allow connectivity from your EKS cluster's VPC. +
    • + +
    + + + +# Tutorial + +### Setup MySQL database and table for the tutorial +This will create a database named `otterize_tutorial` and a table named `example` in your MySQL instance. +Our tutorial server will use this database and table to perform `INSERT` and `SELECT` operations. +``` +export MYSQLHOST= +export MYSQLPASSWORD= + +export MYSQL_PWD=$MYSQLPASSWORD +curl ${ABSOLUTE_URL}/code-examples/mysql/db-setup.sql | mysql -u admin -h $MYSQLHOST --verbose +``` +### Deploy tutorial services and request database credentials +This will set up the namespace we will use for our tutorial and deploy the client & server. + +Our server's Deployment spec will specify an annotation on the Pod, which requests that the credentials operator will provision a username and password for the server. +```yaml + template: + metadata: + annotations: + credentials-operator.otterize.com/user-password-secret-name: server-creds +``` +This specifies that the secret `server-creds` will have keys with the username and password to connect to the database. +The secret will only be created once the database is integrated with Otterize Cloud. + +``` shell +kubectl create namespace otterize-tutorial-mysql +kubectl apply -n otterize-tutorial-mysql -f ${ABSOLUTE_URL}/code-examples/mysql/client-server.yaml +kubectl patch deployment -n otterize-tutorial-mysql server --type='json' -p="[{\"op\": \"replace\", \"path\": \"/spec/template/spec/containers/0/env\", \"value\": [{\"name\": \"DB_HOST\", \"value\": \"$MYSQLHOST\"}]}]" +``` + +
    +Expand to see the deployment YAML + +```yaml +{@include: ../../../../static/code-examples/mysql/client-server.yaml} +``` + +
    + +### Deploy a MySQLServerConfig to allow Otterize DB access +```yaml +{@include: ../../../../static/code-examples/mysql/mysqlserverconfig.yaml} +``` + +The above CRD tells Otterize how to access a database instance named `mysql-tutorial-db`, meaning that when intents +are applied requesting access permissions to `mysql-tutorial-db`, Otterize operators will be able to configure +them. + +In this tutorial, we use the admin user to grant Otterize permissions to create users and grant them access to the database. +In a production environment, it is recommended to create a dedicated user for Otterize, and grant it the necessary permissions to create and manage other users. + +:::caution +The type MySQLServerConfig should be considered as sensitive and require high cluster privileges to access. +::: + +Let's apply the above `MySQLServerConfig` so Otterize will know how to access our database instance. +```shell +kubectl apply -f mysqlserverconf.yaml +kubectl patch mysqlserverconfig -n otterize-tutorial-mysql mysql-tutorial-db --type='json' -p="[{\"op\": \"replace\", \"path\": \"/spec/address\", \"value\": \"$MYSQLHOST\"}, {\"op\": \"replace\", \"path\": \"/spec/credentials/password\", \"value\": \"$MYSQLPASSWORD\"}]" +``` + +### View logs for the server +After the client, server, and database are up and running, we can see that the server does not have the appropriate access to the database by inspecting the logs with the following command. + +```shell +kubectl logs -f -n otterize-tutorial-mysql deploy/server +``` + +Example log: + +Unable to perform INSERT operation +

    +Unable to perform SELECT operation +     + +### Define your ClientIntents + +ClientIntents are Otterize’s way of defining access through unique relationships, which lead to perfectly scoped access. In this example, we provide our `server` workload the ability to insert and select records to allow it to access the database. + +Below is our `intents.yaml` file. As you can see, it is scoped to our database named `otterize_tutorial` and our `example` table. We also have limited the access to just `SELECT` and `INSERT` operations. We could add more databases, tables, or operations if our service required more access. + +Specifying the table and operations is optional. If you don't specify the table, access will be granted to all tables in the specified database. If you don't specify the operations, all operations will be allowed. +```yaml +{@include: ../../../../static/code-examples/mysql/clientintents.yaml} +``` +We can now apply our intents. Behind the scenes,the Otterize credentials-operator created the user for our `server` workload while the intents-operator ran `GRANT` queries on the database, making our `SELECT` and `INSERT` errors disappear. + +```shell +kubectl apply -n otterize-tutorial-mysql -f ${ABSOLUTE_URL}/code-examples/mysql/clientintents.yaml +``` + +### View logs for the server +We can now view the server logs once again. This time, we should see that the server has the appropriate access to the database: + +```shell +kubectl logs -f -n otterize-tutorial-mysql deploy/server +``` + +Example log: + +Successfully INSERTED into our table + +Successfully SELECTED, most recent value: 2024-04-30T13:20:46Z + + +That’s it! If your service’s functionality changes, adding or removing access is as simple as updating your ClientIntents definitions. For fun, try altering the `operations` to just `SELECT` or `INSERT`. + +# Teardown +To remove the deployed examples, run: +```shell +kubectl delete namespace otterize-tutorial-mysql +``` diff --git a/docs/features/postgresql/index.mdx b/docs/features/postgresql/index.mdx index 9355e2e12..494066693 100644 --- a/docs/features/postgresql/index.mdx +++ b/docs/features/postgresql/index.mdx @@ -104,7 +104,7 @@ spec: service: name: server calls: - - name: postgres-tutorial-db # Same name as our PostgresSQLServerConfig metadata.name + - name: postgres-tutorial-db # Same name as our PostgreSQLServerConfig metadata.name type: database databaseResources: - databaseName: otterize-tutorial diff --git a/docs/features/postgresql/reference.mdx b/docs/features/postgresql/reference.mdx index 61f63b245..351f9b165 100644 --- a/docs/features/postgresql/reference.mdx +++ b/docs/features/postgresql/reference.mdx @@ -3,6 +3,19 @@ sidebar_position: 3 title: Reference --- +### PostgreSQLServerConfig example (YAML) +```yaml +apiVersion: k8s.otterize.com/v1alpha3 +kind: PostgreSQLServerConfig +metadata: + name: postgres-tutorial-db # database instance name - should match the target in ClientIntents +spec: + address: # Your Postgres address + credentials: + username: # Username Otterize will connect with & configure permissions as + password: # Password for above username +``` + ### ClientIntents example (YAML) ```yaml @@ -16,7 +29,7 @@ spec: # Service requiring access to PostgreSQL name: server calls: - # This name will need to match the provided integration name + # This name will need to match the PostgreSQLServerConfig metadata.name field - name: otterize-tutorial-postgres type: database databaseResources: diff --git a/docs/features/postgresql/tutorials/postgres.mdx b/docs/features/postgresql/tutorials/postgres.mdx index f73c08b34..d40e7d8f1 100644 --- a/docs/features/postgresql/tutorials/postgres.mdx +++ b/docs/features/postgresql/tutorials/postgres.mdx @@ -136,7 +136,7 @@ spec: service: name: server calls: - - name: postgres-tutorial-db # Same name as our PostgresSQLServerConfig metadata.name + - name: postgres-tutorial-db # Same name as our PostgreSQLServerConfig metadata.name type: database databaseResources: - databaseName: otterize-tutorial diff --git a/static/code-examples/mysql/client-server.yaml b/static/code-examples/mysql/client-server.yaml new file mode 100644 index 000000000..7329c3934 --- /dev/null +++ b/static/code-examples/mysql/client-server.yaml @@ -0,0 +1,79 @@ +apiVersion: apps/v1 +kind: Deployment +metadata: + name: server +spec: + replicas: 1 + selector: + matchLabels: + app: server + template: + metadata: + annotations: + credentials-operator.otterize.com/user-password-secret-name: server-creds + labels: + app: server + spec: + serviceAccountName: server + containers: + - name: server + imagePullPolicy: Always + image: 'otterize/mysql-tutorial-server' + ports: + - containerPort: 80 + env: + - name: DB_HOST + value: database + - name: DB_NAME + value: otterize_example + - name: DB_PORT + value: "3306" + - name: DB_SERVER_USER + valueFrom: + secretKeyRef: + name: server-creds + key: username + - name: DB_SERVER_PASSWORD + valueFrom: + secretKeyRef: + name: server-creds + key: password +--- +apiVersion: v1 +kind: Service +metadata: + name: server +spec: + type: ClusterIP + selector: + app: server + ports: + - name: http + port: 80 + targetPort: 80 +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: server +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: client +spec: + replicas: 1 + selector: + matchLabels: + app: client + template: + metadata: + labels: + app: client + spec: + containers: + - name: client + imagePullPolicy: Always + image: 'otterize/mysql-tutorial-client' + ports: + - containerPort: 80 diff --git a/static/code-examples/mysql/clientintents.yaml b/static/code-examples/mysql/clientintents.yaml new file mode 100644 index 000000000..9ff46286b --- /dev/null +++ b/static/code-examples/mysql/clientintents.yaml @@ -0,0 +1,16 @@ +apiVersion: k8s.otterize.com/v1alpha3 +kind: ClientIntents +metadata: + name: server +spec: + service: + name: server + calls: + - name: otterize-tutorial-mysql + type: database + databaseResources: + - databaseName: otterize_example + table: example + operations: + - SELECT + - INSERT \ No newline at end of file diff --git a/static/code-examples/mysql/db-setup.sql b/static/code-examples/mysql/db-setup.sql new file mode 100644 index 000000000..cc4340a9d --- /dev/null +++ b/static/code-examples/mysql/db-setup.sql @@ -0,0 +1,9 @@ +CREATE DATABASE IF NOT EXISTS otterize_example; + +USE otterize_example; + +CREATE TABLE IF NOT EXISTS example +( + file_name VARCHAR(255), + upload_time BIGINT +); \ No newline at end of file diff --git a/static/code-examples/mysql/mysqlserverconfig.yaml b/static/code-examples/mysql/mysqlserverconfig.yaml new file mode 100644 index 000000000..c4802f67c --- /dev/null +++ b/static/code-examples/mysql/mysqlserverconfig.yaml @@ -0,0 +1,9 @@ +apiVersion: k8s.otterize.com/v1alpha3 +kind: MySQLServerConfig +metadata: + name: mysql-tutorial-db +spec: + address: database # Your MySQL server address + credentials: + username: admin # Your MySQL server user + password: password # Your MySQL server password \ No newline at end of file diff --git a/static/img/icons/mysql.svg b/static/img/icons/mysql.svg new file mode 100644 index 000000000..53371d09b --- /dev/null +++ b/static/img/icons/mysql.svg @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/static/img/quick-tutorials/mysql/social.png b/static/img/quick-tutorials/mysql/social.png new file mode 100644 index 000000000..017350f79 Binary files /dev/null and b/static/img/quick-tutorials/mysql/social.png differ