Skip to content

Commit

Permalink
[#1422] AWS Docs Revamp (#1487)
Browse files Browse the repository at this point in the history 
* [#1422] AWS Docs Revamp

* Update docs/docs/getting-started/installation/aws.md

Co-authored-by: lucapette <ciao@lucapette.me>

* Update docs/docs/getting-started/installation/aws.md

Co-authored-by: lucapette <ciao@lucapette.me>

* Using ::note to explicit requirements

* Fixing the asciinema cast

Co-authored-by: lucapette <ciao@lucapette.me>
Co-authored-by: ljupcovangelski <ljupco@airy.co>
  • Loading branch information
@paulodiniz @lucapette @ljupcovangelski
3 people authored Apr 9, 2021
1 parent 7bdfdcd commit 341d579
Show file tree
Hide file tree
Showing 3 changed files with 118 additions and 31 deletions.
109 changes: 92 additions & 17 deletions docs/docs/getting-started/installation/aws.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: AWS
title: Run Airy on AWS
sidebar_label: AWS
---

Expand All @@ -8,30 +8,70 @@ import TLDR from "@site/src/components/TLDR";
import SuccessBox from "@site/src/components/SuccessBox";
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import ButtonBox from "@site/src/components/ButtonBox";
import DiamondSVG from "@site/static/icons/diamond.svg";

<TLDR>

Run Airy Core on AWS with one command.

</TLDR>

The goal of this document is to provide an overview of how to run Airy Core on
AWS cloud platform, using the [AWS Elastic Kubernetes Service](https://aws.amazon.com/eks/).
AWS cloud platform, using the [AWS Elastic Kubernetes
Service](https://aws.amazon.com/eks/).

## Configure AWS

:::note

Prior to starting this guide, you must create an [AWS
account](https://aws.amazon.com/free). We also recommend installing the [AWS
CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html).

:::

Once you have installed the AWS CLI, you now need to configure the application
to be able to connect to your AWS account:

```
aws configure
```

Through `aws configure`, the AWS CLI will prompt you for four pieces of
information. The first two are required. These are your [AWS access key ID and
AWS secret access
key](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html),
which serve as your account credentials. You can generate new credentials within
AWS Identity and Access Management (IAM) if you do not already have them. The
other information you will need is region and output format, which you can leave
as default for the time being.

```
aws configure
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-west-2
Default output format [None]: json
```

Apart from the EKS cluster, the installation will create all the necessary AWS resources, such as:
Apart from an EKS cluster, `airy create` will take car of all the necessary AWS
resources, such as:

- VPC resources (VPC, subnets, route tables, public gateways)
- IAM roles and policy attachments
- EKS cluster and EKS node groups
- EC2 instances, as part of the created node group

## Creating a cluster
## Create a cluster

For creating the cluster you would need to setup your local AWS environment, by [configuring your local AWS profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) for the AWS account where all the resources will be created.
To create the cluster you must setup your local AWS environment, by [configuring
your local AWS
profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)
for the AWS account where all the resources will be created.

Download and install the [Airy CLI](cli/introduction.md).

Export your AWS_PROFILE as described in the [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html).
Export your AWS_PROFILE as described in the [AWS
documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html).

Now you can run this command, which will create Airy core in your AWS account:

Expand All @@ -41,21 +81,48 @@ airy create --provider=aws

This will execute the following actions:

1. Create the `my-airy` directory and populate it with the configuration that the CLI will need. All subsequent commands need to either be run from this directory or use the `--config-dir` flag.
1. Create the `my-airy` directory and populate it with the configuration that
the CLI will need. All subsequent commands need to either be run from this
directory or use the `--config-dir` flag.
2. Start an Airy Core cluster in your AWS account.
3. Print URLs for accessing the UIs and APIs (see recording).

By default, the installation will create a single EC2 Kubernetes node, as part of a single node group. You can scale your EKS cluster by adding more nodes or node groups through the AWS web console or the AWS CLI.
By default, the installation will create a single EC2 Kubernetes node, as part
of a single node group. You can scale your EKS cluster by adding more nodes or
node groups through the AWS web console or the AWS CLI.

import Script from "@site/src/components/Script";

<Script data-cols="120" data-rows="32" id="asciicast-PR1ZSQICDMm9JhtzJIVdg9HQX" src="https://asciinema.org/a/PR1ZSQICDMm9JhtzJIVdg9HQX.js"></Script>
<Script data-cols="120" data-rows="32" id="asciicast-HwezTgcr35UnwLpSviktLICEZ" src="https://asciinema.org/a/HwezTgcr35UnwLpSviktLICEZ.js"></Script>

If you want to customize your `Airy Core` instance please see our [Configuration
Section](configuration.md).

After the installation, you can also interact with the components of `Airy Core`
with the [kubectl](https://kubernetes.io/docs/tasks/tools/) command line
utility. You can find the kubeconfig of your Airy Core instance in
`~/.airy/kube.conf`.

### Verification

If you want to customize your `Airy Core` instance please see our [Configuration Section](configuration.md).
After the installation process, you can verify that all the pods are running with

```
kubectl get pods --kubeconfig ./kube.conf
```

After the installation, you can also interact with the components of `Airy Core` with the [kubectl](https://kubernetes.io/docs/tasks/tools/) command line utility. You can find the kubeconfig of your Airy Core instance in `~/.airy/kube.conf`.
### Common issues

## Public webhooks
AWS has a limit on the number of objects you can create depending on your account.

```
Error creating vpc: operation error EC2: CreateVpc, https response error StatusCode: 400, RequestID: 64210ff5-9aca-4ab7-b993-3727637a59d6, api error VpcLimitExceeded: The maximum number of VPCs has been reached.
```

When encountering this, you can delete some of the resources just as described
on [here](/getting-started/installation/aws#uninstall-airy-core)

## Integrate public webhooks

The public webhooks will be accessible on the public LoadBalancer which is
created by the Ingress loadBalancer Kubernetes service.
Expand All @@ -66,10 +133,18 @@ To get the public URL of your AWS Airy Core installation you can run:
kubectl --kubeconfig ~/.airy/kube.conf get --namespace kube-system service traefik --output jsonpath='{.status.loadBalancer.ingress[0].hostname}'
```

## Where to go from here
## Next steps

Now that you have a running installation of Airy core on AWS you can connect it
to messaging sources. Check out our quickstart guide:

Now that you have a running installation of Airy core on AWS you can connect it to messaging sources. Check out the
[source documentation](/sources/introduction.md) to learn more.
<ButtonBox
icon={<DiamondSVG />}
iconInvertible={true}
title='To the Quick Start'
description='Learn the Airy Basics with our Quick Start'
link='getting-started/quickstart'
/>

## Third party tools

Expand Down
30 changes: 16 additions & 14 deletions docs/docs/getting-started/installation/minikube.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,17 @@ sidebar_label: Minikube
import TLDR from "@site/src/components/TLDR";

<TLDR>
Run Airy on minikube with one command
Run Airy on minikube with one command.
</TLDR>

The goal of this document is to provide an overview of how to run Airy Core on
your local machine using [minikube](https://minikube.sigs.k8s.io/).

## Creating a cluster
## Create a minikube cluster

First download and install minikube from their [release
page](https://github.com/kubernetes/minikube/releases) and the [Airy CLI](cli/introduction.md). Now you can run this command, which will create a new
page](https://github.com/kubernetes/minikube/releases) and the [Airy
CLI](cli/introduction.md). Now you can run this command, which will create a new
minikube cluster on your system and install Airy core on it:

```bash
Expand All @@ -38,15 +39,15 @@ Section](configuration.md).
After the installation, you can also interact with the components of `Airy Core` with the [kubectl](https://kubernetes.io/docs/tasks/tools/) command line utility.
`airy create` adds the kubeconfig of your Airy Core instance to the default kubeconfig file `~/.kube/config`, under the context `airy-core`.

## Public webhooks
## Integrate public webhooks

In order to integrate with the webhook of most sources on your local machine,
we include a [ngrok](https://ngrok.com/) as a deployment to tunnel the traffic to the ingress controller.
ngrok is an open source reverse proxy which
creates a secure tunnel from a public endpoint to a local service. The ngrok
client connects to a ngrok server which has public access to the internet and
then provides a reversed proxy connectivity back to the webhook services,
running inside the Kubernetes cluster.
In order to integrate with the webhook of most sources on your local machine, we
include a [ngrok](https://ngrok.com/) as a deployment to tunnel the traffic to
the ingress controller. ngrok is an open source reverse proxy which creates a
secure tunnel from a public endpoint to a local service. The ngrok client
connects to a ngrok server which has public access to the internet and then
provides a reversed proxy connectivity back to the webhook services, running
inside the Kubernetes cluster.

To get the ngrok URL of your local Airy Core installation you can run:

Expand Down Expand Up @@ -74,10 +75,11 @@ If you prefer to use your own ngrok implementation or point the ngrok client to
connect to the service provided by the ngrok company at `https://ngrok.io`,
change the setting for `server_addr` in the ConfigMap.

## Where to go from here
## Next steps

Now that you have a running local installation of Minikube you can connect it to messaging sources. Check out the
[source documentation](/sources/introduction.md) to learn more.
Now that you have a running local installation of Minikube you can connect it to
messaging sources. Check out the [source
documentation](/sources/introduction.md) to learn more.

## Third party tools

Expand Down
10 changes: 10 additions & 0 deletions docs/docs/getting-started/introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,16 @@ conversational platform.

<Image lightModePath="img/getting-started/introduction-light.png" darkModePath="img/getting-started/introduction-dark.png"/>

<h3>Get Airy up and running with one command</h3>

```bash
# Install the Airy CLI
brew install airyhq/airy/cli

# Create Airy with one command
airy create --provider=aws
```

## What Airy is used for

With Airy Core you can process conversational data from a variety of sources:
Expand Down

0 comments on commit 341d579

Please sign in to comment.