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

Update deployment docs #378

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update deployment docs #378

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
abfa3f6
Update deployment docs
natoverse Jan 31, 2023
5f12736
Update README.md
natoverse Feb 1, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ This interface allows users to inspect variable relationships within data, and t

**Note: At the moment, ShowWhy does not work with Apple Mxx processors in local mode.**

To run the application locally,ensure that you have Docker installed and running on your machine. You can find instructions for installing Docker [here](https://docs.docker.com/get-docker/).
To run the application locally, ensure that you have Docker installed and running on your machine. You can find instructions for installing Docker [here](https://docs.docker.com/get-docker/).

Open up a terminal application, and using the command-line interface (CLI) run the following command:

Expand All @@ -48,7 +48,9 @@ For developers wishing to contribute to the project, refer to [DEVELOPING.md](./

[![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2Fshowwhy%2Fmain%2Fdocs%2Fdeployment%2Fazure-scripts%2Fall.json)

Check the [deployment documentation](./docs/deployment/README.md) for instructions on how to deploy to deploy SHowWhy to Azure AKS (either via one-click or manually), and how to deploy ShowWhy into a local Kubernetes instance.
This deploy button will take you directly to Azure to create a resource deployment of ShowWhy.

Check the [deployment documentation](./docs/deployment/README.md) for more details and instructions on how to deploy to deploy ShowWhy to Azure AKS (either via one-click or manually), and how to deploy ShowWhy into a local Kubernetes instance.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'to deploy' is duplicated here


# Contribute

Expand Down
2 changes: 1 addition & 1 deletion docs/deployment/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,4 @@ ShowWhy is split between a front-end web-based client and a containerized Python
## Deployment Options
Our team deploys ShowWhy using Azure AKS. See the [Azure Deployment documentation](./azure-scripts/README.md) for details.

If you are interested in testing out a deployment configuration locally using Kubernetes, see the [local deployment](./LOCAL_DEPLOY.md) instructions. Please note that this should only be used for debugging infrastructural issues. For application development or for test-driving the application locally the `Getting Started` instructions in README.md are much simpler and will be less demanding on your machine.
If you are interested in testing out a deployment configuration locally using Kubernetes, see the [local deployment](./LOCAL_DEPLOY.md) instructions. Please note that this should only be used for debugging infrastructural issues. For application development or for test-driving the application locally the [getting started](../../README.md#getting-started) instructions are much simpler and will be less demanding on your machine.
92 changes: 37 additions & 55 deletions docs/deployment/azure-scripts/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,43 @@
# AKS ARM Template
This Azure Resource Manager (ARM) template deploys an Azure Kubernetes Service (AKS) cluster with the specified parameters. The template also includes Helm, a package manager for Kubernetes.
The Azure Resource Manager (ARM) template deploys an Azure Kubernetes Service (AKS) cluster with the specified parameters. The template also includes Helm, a package manager for Kubernetes.

[![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2Fshowwhy%2Fmain%2Fdocs%2Fdeployment%2Fazure-scripts%2Fall.json)

The button will run the ARM template in Azure with a set of reasonable defaults, and should execute with no problems if you have the permissions to create the resources. If you think you need authentication, please read [those instructions](#create-authentication) below first.

**Please note that:**

**1. You must have:
Microsoft.Authorization/roleAssignments/write permissions, such as `User Access Administrator` or `Owner`.**
**1. You must have: Microsoft.Authorization/roleAssignments/write permissions, such as `User Access Administrator` or `Owner`.**

**2. The aks cluster will be only accessible by Azure Portal, it's not generating a ssh key for external access.**

**3. The application will have a self-signed certificate, when you access it you will se an error stating "Your connection is not private".**
**3. The application will run with SSL using a self-signed certificate: when you access it your browser will se an error stating "Your connection is not private".**

## Parameters:
`Subscription`: The subscription to be billed for the resources.

`ResourceGroup`: The collection of resources for this to be deployed to.

`Region`: The region for the resources. If you chose an existing resource group, it will default to it.

`clusterName`: The name of the Managed Cluster resource.

`dnsPrefix`: Optional DNS prefix to use with hosted Kubernetes API server FQDN ({dnsPrefix}.{location}.cloudapp.azure.com).

`osDiskSizeGB`: Disk size (in GB) to provision for each of the agent pool nodes. This value ranges from 0 to 1023. Specifying 0 will apply the default disk size for that agentVMSize.
- `Subscription`: The subscription to be billed for the resources.
- `ResourceGroup`: The collection of resources for this to be deployed to.
- `Region`: The region for the resources. If you chose an existing resource group, it will default to it the region for that group.
- `clusterName`: The name of the Managed Cluster resource to create.
- `dnsPrefix`: DNS prefix to use with hosted Kubernetes API server FQDN ({dnsPrefix}.{location}.cloudapp.azure.com). This will create a unique URL for your application.
- `osDiskSizeGB`: Disk size (in GB) to provision for each of the agent pool nodes. This value ranges from 0 to 1023. Specifying 0 will apply the default disk size for that agentVMSize.
- `agentCount`: The number of nodes for the cluster.
- `agentVMSize`: The size of the Virtual Machine (SKU). Note that this VM option must be available in the region you select. We can't get a list dynamically in the script, so if you're unsure please use the [product finder](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/). Our script default VM (Standard_D2s_v3) is available in the default region (East US 2).

`agentCount`: The number of nodes for the cluster.
If you don't need authentication securing the application, you can proceed to **Review + create** now. Otherwise, create or open your auth app to get the values for the last two parameters:

`agentVMSize`: The size of the Virtual Machine.
- `clientId`: Client ID from the app registration
- `clientSecret`: Client Secret from the app registration

If you wounld't like any form of authentication you can proceed to Review + create.
## Create authentication

<details id="section-1"><summary>Deploy with authentication</summary>
It's up to you whether you add authentication to protect your instance. ShowWhy does not store user data or "accounts", and only retains uploaded input data on the server for a few hours in a cache to reduce network traffic while you use the application. However, if you want to be sure your data is fully protected, you can create an authentication app and connect it to the instance.

To authenticate requests made to the services in the cluster we will use the [OAuth2 Proxy](https://oauth2-proxy.github.io/oauth2-proxy/) service.
To authenticate requests made to the services in the cluster we use the [OAuth2 Proxy](https://oauth2-proxy.github.io/oauth2-proxy/) service.

We need to create our APP registration on Azure Active Directory:

- concatename the parameters to create the DOMAIN value: {dnsPrefix}.{location}.cloudapp.azure.com
> NOTE: construct the `DOMAIN` value used below like so: `{dnsPrefix}.{region}.cloudapp.azure.com`

1. Create the new APP registration (Single tenant).
2. In the `Overview` left menu, the Application (client) ID will be the `{clientId}` used below.
Expand All @@ -49,50 +49,32 @@ We need to create our APP registration on Azure Active Directory:
6. In the `Expose an API` left menu, click on `set` near to `Application ID URI`, use the suggested value and click `Save`.
7. In the `Manifest` left menu, add or update the `accessTokenAcceptedVersion` in the JSON config to `2` (integer, not string - `"accessTokenAcceptedVersion": 2`).

## Parameters:

`clientId`: Client ID from the app registration

`clientSecret`: Client Secret from the app registration
## Add authentication after deployment

</details>
If you've already created a deployment and want to update it later with authentication you can do so with this modified script.

<details><summary>Add authentication after deployment</summary>

You can add authentication later if you want.
1. Follow the above example on `Deploy with authentication` to create a new APP registration
2. Click the button to deploy the authentication script:
1. Follow the above instructions under "Create authentication" to create a new APP registration
2. Click the button to deploy the authentication-adding script:

[![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2Fshowwhy%2Fmain%2Fdocs%2Fdeployment%2Fazure-scripts%2Fauth.json)

## Parameters:
`Subscription`: The subscription of the existing cluster.
### Parameters:

`Resource group`: The resource group of the existing cluster
Most of the parameters are the same as for creating the new deployment. Otherwise:

`Region`: Will default to the resource group's region.
- `clusterName`: The name of the *existing* cluster.
- `identityName`: In the existing Resource group, copy the name of the resource with type "Managed Identity"
- `helmAppLocation`: The helm script to install the dependencies (leave the default)
- `domain`: Full URL of the application

`Cluster Name`: The name of the existing cluster.
## Alternate deployment
To deploy the template manually you can use the Azure Portal, Azure PowerShell, or the Azure CLI instead of the buttons on this page.

`Identity Name`: In the existing resource group, copy the name of the resource of Type: `
Managed Identity`

`Helm App Location`: The helm script to install the dependencies (leave the default)

`clientId`: Client ID from the app registration

`clientSecret`: Client Secret from the app registration

`domain`: Full URL of the application

</details>

## Deployment
To deploy the template, you can use the Azure portal, Azure PowerShell, or the Azure CLI.

In the Azure portal, select Create a resource, search for "AKS ARM Template", and select it from the results.
In the Azure Portal, select "Create a resource", search for "AKS ARM Template", and select it from the results.
Follow the prompts to enter the required parameters and confirm it.
This will create two resource groups, one with the resource group name that yopu passed and a second one starting with MC_{RESOURCE_GROUP}_{CLUSTER_NAME}_{REGION}.

## Output
`url`: The url to access your deployed platform

This script will create two resource groups, one with the resource group name that you specified and a second one starting named like `MC_{RESOURCE_GROUP}_{CLUSTER_NAME}_{REGION}` (this is created to contain managed cluster infrastructure resources for Kubernetes).

The URL to access your application will be composed of the DNS prefix you chose and the region, like `https://{dnsPrefix}.{region}.cloudapp.azure.com`. You can find it by looking in the MC resource group and finding the Kubernetes public IP.