diff --git a/.github/config/en-custom.txt b/.github/config/en-custom.txt index 4898f151..e010d27c 100644 --- a/.github/config/en-custom.txt +++ b/.github/config/en-custom.txt @@ -1513,4 +1513,5 @@ ResetFloor IANA DateTime durations -whitespace \ No newline at end of file +whitespace +subcommand \ No newline at end of file diff --git a/docs/content/how-to-guides/configure-reactions/configure-drasi-debug-reaction/_index.md b/docs/content/how-to-guides/configure-reactions/configure-drasi-debug-reaction/_index.md index a2e0b2a3..b047b906 100644 --- a/docs/content/how-to-guides/configure-reactions/configure-drasi-debug-reaction/_index.md +++ b/docs/content/how-to-guides/configure-reactions/configure-drasi-debug-reaction/_index.md @@ -35,9 +35,7 @@ spec: queries: hello-world-from: message-count: - inactive-people: - endpoints: - gateway: 8080 + inactive-people: ``` In this definition: @@ -50,7 +48,8 @@ This table describes the other settings in the **spec** section of the Reaction |Property|Description| |-|-| |queries|Specifies the set of **names** of the Continuous Queries the Reaction will subscribe to.| -|endpoints.gateway|Specifies the **port** on which the Drasi Debug Reaction will expose its Web UI. If not specified, this defaults to 8080. | + +By default, the Drasi Debug Reaction will expose its Web UI on port 8080. If you wish to create an ingress for the Debug Reaction, please refer to the [Ingress documentation](/reference/ingress/) for more information. ## Inspecting the Reaction As soon as the Reaction is created it will start running, subscribing to the specified list of Continuous Queries and processing changes to the Continuous Query results. diff --git a/docs/content/how-to-guides/configure-reactions/configure-drasi-result-reaction/_index.md b/docs/content/how-to-guides/configure-reactions/configure-drasi-result-reaction/_index.md index 0e73bb23..c01e7e41 100644 --- a/docs/content/how-to-guides/configure-reactions/configure-drasi-result-reaction/_index.md +++ b/docs/content/how-to-guides/configure-reactions/configure-drasi-result-reaction/_index.md @@ -36,8 +36,6 @@ spec: kind: Result queries: query1: - endpoints: - gateway: 8080 properties: QueryContainerId: default ``` @@ -52,9 +50,10 @@ This table describes the other settings in the **spec** section of the Reaction |Property|Description| |-|-| |queries|Specifies the set of **names** of the Continuous Queries the Reaction will subscribe to.| -|endpoints.gateway|Specifies the **port** on which the Drasi Result Reaction operates. If not specified, this defaults to 8080. | |properties.QueryContainerId|Specifies the ID of the Query Container where the Continuous Query resides. If this field is not set, the ID `default` will be used, which is the default Query Container ID created during `drasi init`.| +By default, the Drasi Result Reaction will expose its Web UI on port 8080. If you wish to create an ingress for the Result Reaction, please refer to the [Ingress documentation](/reference/ingress/) for more information. + ## Inspecting the Reaction As soon as the Reaction is created it will start running, subscribing to the specified list of Continuous Queries and processing changes to the Continuous Query results. diff --git a/docs/content/how-to-guides/configure-reactions/configure-signalr-reaction/_index.md b/docs/content/how-to-guides/configure-reactions/configure-signalr-reaction/_index.md index 7c558d6c..f35221ea 100644 --- a/docs/content/how-to-guides/configure-reactions/configure-signalr-reaction/_index.md +++ b/docs/content/how-to-guides/configure-reactions/configure-signalr-reaction/_index.md @@ -67,6 +67,8 @@ This table describes the other settings in the **spec** section of the Reaction | identity | The service identity provider used for authentication to the Azure SignalR Service, discussed below. | +By default, the Drasi SignalR Reaction will expose its Web UI on port 8080. If you wish to create an ingress for the SignalR Reaction, please refer to the [Ingress documentation](/reference/ingress/) for more information. + ### Identity The reaction supports the following service identities: diff --git a/docs/content/reference/command-line-interface/_index.md b/docs/content/reference/command-line-interface/_index.md index 0627df9d..0d251f5e 100644 --- a/docs/content/reference/command-line-interface/_index.md +++ b/docs/content/reference/command-line-interface/_index.md @@ -54,6 +54,7 @@ Available Commands: describe Show the definition and status of a resource env Manage Drasi environment configurations. help Help about any command + ingress Manage ingress controllers for Drasi Sources and Reactions init Install Drasi list Show a list of available resources namespace Manage CLI namespace settings @@ -336,6 +337,24 @@ drasi env use docker ### drasi help **Purpose**: The `help` command provides detailed help information about Drasi CLI commands. It is useful for understanding the usage, flags, and arguments of various commands available in the Drasi CLI. See the [Get Help](#get-help) section above. +### drasi ingress +**Purpose**: The `ingress` command manages the Kubernetes Ingress controller that Drasi uses by default. It includes the `drasi ingress init` subcommand. + +#### drasi ingress init +**Purpose**: The `drasi ingress init` command initializes the Ingress controller for use with Drasi. It can either install and configure the Contour ingress controller automatically, or integrate with existing ingress controllers already deployed to your cluster using the `--use-existing` flag. + +**Flags and Arguments**: +- `--use-existing` (optional): If set, the command will attempt to integrate with an existing ingress controller in the cluster instead of installing the Contour ingress controller. If this flag is set, then the `--ingress-class-name` flag must be set. +- `--gateway-ip-address ` (optional): Public IP address of the Load Balancer (used when using AGIC or AWS Load Balancer Controller) +- `--ingress-service-name ` (optional): The name of the Kubernetes service for the existing ingress controller (useful when using an ingress controller is already deployed in the cluster) +- `--ingress-namespace ` (optional): The namespace where the existing ingress controller service is located (useful when using an ingress controller is already deployed in the cluster) +- `--ingress-class-name ` (required when `--use-existing` is set): The class name that the Kubernetes ingress resource will use. It lets the ingress controller know which class of ingress it should handle. + +**Usage example**: + + +{{< read file= "/shared-content/ingress/ingress-init.md" >}} + ### drasi init **Purpose**: The `init` command is used to install a Drasi environment to the Kubernetes cluster that is the **current context** in `kubectl` ([see above](#target-the-drasi-environment)). By default, the Drasi environment will be installed into the `drasi-system` namespace, but this can be overridden as described below. @@ -453,12 +472,22 @@ When listing static resources like `sourceprovider` and `reactionprovider`, the CosmosGremlin ``` -When listing `querycontainer`, `source`, and `reaction` resources, the output is a table showing the name of the resource and a status showing whether the resource is available, like this list of **Query Containers**: +When listing querycontainer, source, and reaction resources, the output is a table showing the ID of the resource, an availability status indicating whether the resource is available, and any error messages, like this list of **Sources**: + +``` +drasi list source + ID | AVAILABLE | MESSAGES +--------------+-----------+----------- + hello-world | true | +``` + +If the resource contains an ingress, `drasi list` will also display the ingress URL: ``` - ID | AVAILABLE -----------+------------ - default | true +drasi list reaction + ID | AVAILABLE | INGRESS URL | MESSAGES +--------------------+-----------+----------------------------------------------------+----------- + hello-world-debug | true | http://hello-world-debug.drasi.x.xxx.xx.xxx.nip.io | ``` When listing `continuousquery` (or `query`) resources, the output is a table the shows where the **Continuous Query** is running and what its current status is. Here is an example containing multiple **Continuous Queries**, two of which are `Running` and one of which is in a `TerminalError` state: diff --git a/docs/content/reference/ingress/_index.md b/docs/content/reference/ingress/_index.md new file mode 100644 index 00000000..f3ac1ae2 --- /dev/null +++ b/docs/content/reference/ingress/_index.md @@ -0,0 +1,119 @@ +--- +type: "docs" +title: "Ingress" +linkTitle: "Ingress" +weight: 60 +description: > + Deploy and manage Kubernetes ingress resources for your Drasi resources. +--- + +Drasi allows you to deploy and manage Kubernetes ingress resources for your applications easily in your Drasi YAML file, without using `kubectl`. You can use the Drasi CLI to install [Contour](https://projectcontour.io/) as your ingress controller, or use an existing ingress controller that is already deployed in your Kubernetes cluster. + +Currently, Drasi only support deploying ingress resources for Drasi Sources and Reactions. + + +### Ingress Initialization + +You can initialize ingress in your Drasi environment using the CLI. + +{{< read file= "/shared-content/ingress/ingress-init.md" >}} + +For more information on the `drasi ingress` command, refer to the [Drasi CLI documentation](/reference/command-line-interface/#drasi-ingress). + + +### Ingress Configuration +You can configure ingress deployment for your Source or Reaction by setting the `gateway` field in your YAML file. To expose an endpoint externally, set the `setting` field to external and specify a port number in the `target` field. This target port will be used for the Kubernetes Service that gets provisioned alongside the Ingress resource. + +Below is a sample YAML file for a Debug Reaction. In this example, we are configuring an endpoint called `ingress` to be an external endpoint: +```yaml +apiVersion: v1 +kind: Reaction +name: hello-world +spec: + kind: Debug + queries: + query1 + services: + reaction: + endpoints: + ingress: + setting: external + target: "8080" +``` + +After running `drasi apply`, you can view the Ingress URL by running the `drasi list` command. For example: + +```bash +drasi apply -f reaction.yaml +✓ Apply: Reaction/hello-world: complete +drasi list reaction + ID | AVAILABLE | INGRESS URL | MESSAGES +--------------------+-----------+----------------------------------------------------+----------- + hello-world-debug | true | http://hello-world-debug.drasi.x.xxx.xx.xxx.nip.io | +``` + +The URL follows the pattern `http://{name}.drasi.{loadbalancer-ip}.nip.io`, where: + +- `{name}` is the name of the Ingress resource +- `{loadbalancer-ip}` is the load balancer IP address of the Ingress controller service + +If you are using AWS Load Balancer Controller for EKS, the Ingress URL will be different. The controller provisions an Application Load Balancer (ALB) and assigns a DNS name to it. + +### Using Azure Application Gateway Ingress Controller (AGIC) for AKS +The Application Gateway Ingress Controller (AGIC) is a Kubernetes application that enables AKS customers to leverage Azure's native Application Gateway L7 load-balancer to expose services to the Internet. AGIC monitors your Kubernetes cluster and continuously updates the Application Gateway configuration. + +#### Prerequisites +- An AKS cluster with Drasi installed. See this [link](/how-to-guides/installation/install-on-aks/) for installation instructions. +- az CLI + + +#### AGIC installation +AGIC can be installed on a new AKS cluster either via Helm or as an add-on. This [tutorial](https://review.learn.microsoft.com/en-us/azure/application-gateway/tutorial-ingress-controller-add-on-new?branch=main) will guide you through the installation process. + +#### Drasi configuration +First, get credentials to the AKS cluster by running the `az aks get-credentials` command: +```bash +az aks get-credentials -n myCluster -g myResourceGroup +``` + +Set the Drasi context to the AKS cluster: + +```bash +drasi env kube +``` + +Obtain the public IP address of the Application Gateway from the Azure portal; this IP address will be used as the `--gateway-ip-address` when configuring Drasi. + +Execute the following command to configure Drasi with the Application Gateway IP address: + +```bash +drasi ingress init --use-existing --ingress-class-name azure-application-gateway --gateway-ip-address +``` + +### Using AWS Load Balancer Controller for EKS +The AWS Load Balancer Controller manages AWS Elastic Load Balancers for Kubernetes clusters, enabling you to expose cluster applications to the internet. It provisions Application Load Balancers (ALBs) for Kubernetes Ingress resources and Network Load Balancers (NLBs) for Kubernetes Service resources with appropriate annotations. The controller monitors your Kubernetes cluster and automatically configures load balancers based on your Kubernetes resource specifications. + + +#### Prerequisites +- An EKS cluster with Drasi installed. See this [link](/how-to-guides/installation/install-on-eks/) for installation instructions. +- aws CLI + +#### ALB Configuration +Please refer to this [guide](https://docs.aws.amazon.com/eks/latest/userguide/aws-load-balancer-controller.html) for installing AWS Load Balancer Controller. + +#### Drasi configuration +First, get credentials to the EKS cluster by running the `aws eks update-kubeconfig` command: +```bash +aws eks update-kubeconfig --region --name +``` + +Set the Drasi context to the AKS cluster: + +```bash +drasi env kube +``` + +Unlike Azure Application Gateway which requires a static IP address, ALBs are dynamically provisioned with DNS names rather than fixed IP addresses. Execute the following command to configure Drasi with the appropriate ingress class name: +```bash +drasi ingress init --use-existing --ingress-class-name alb +``` \ No newline at end of file diff --git a/docs/shared-content/ingress/ingress-init.md b/docs/shared-content/ingress/ingress-init.md new file mode 100644 index 00000000..d07238c4 --- /dev/null +++ b/docs/shared-content/ingress/ingress-init.md @@ -0,0 +1,32 @@ +To install the Contour ingress controller, run the following command: + +```bash +drasi ingress init +``` +The CLI will use helm to install the Contour ingress controller in the default 'project-contour' namespace. + +To use an existing ingress controller, run the following command: + +```bash +drasi ingress init --use-existing --ingress-service-name --ingress-namespace --ingress-class-name +``` + +For instance, to use an existing NGINX ingress controller with the service name `ingress-nginx-controller` in the `ingress-nginx` namespace, execute the following command. + +```bash +drasi ingress init --use-existing --ingress-service-name nginx-ingress --ingress-namespace ingress-nginx --ingress-class-name nginx +``` + +Additionally, if you are using an Azure Application Gateway or AWS Load Balancer controller as your ingress controller, you can specify the public IP address of the Application Gateway using the `--gateway-ip-address` flag. + +Azure Application Gateway: +```bash +drasi ingress init --use-existing --ingress-class-name azure-application-gateway --gateway-ip-address +``` + +AWS Load Balancer: +```bash +drasi ingress init --use-existing --ingress-class-name alb --gateway-ip-address +``` + +For more information on setting up Azure Application Gateway or AWS Load Balancer controller, refer to this [documentation](/reference/ingress) \ No newline at end of file