Skip to content

Commit

Permalink
Merge branch 'master' of https://github.com/microsoft/TeamCloud
Browse files Browse the repository at this point in the history
  • Loading branch information
@markusheiliger
markusheiliger committed Apr 2, 2020
2 parents 7e20620 + a1b069c commit ba5354e
Show file tree
Hide file tree
Showing 33 changed files with 186 additions and 783 deletions.
92 changes: 20 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,88 +6,46 @@ TeamCloud is a tool that enables enterprise IT organizations to provide applicat

## Concepts

There are several components that make up the TeamCloud solution:
There are several components that make up the TeamCloud solution.

### TeamCloud CLI

The [TeamCloud CLI](docs/CLI.md) is an [extension](https://docs.microsoft.com/en-us/cli/azure/azure-cli-extensions-overview?view=azure-cli-latest) for the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/?view=azure-cli-latest). It can be used by application development teams to create and manage Projects, and by TeamCloud admins to create new TeamCloud instances or manage existing instances.

### TeamCloud Instance

At the center of the tool is a TeamCloud instance (the source code in this repository). An enterprise deploys a single TeamCloud instance, along with one or more Providers, to an Azure subscription managed by its IT organization.
At the center of the tool is a TeamCloud instance (the source code in this repository). An enterprise deploys a single TeamCloud instance, along with one or more Providers, to an Azure subscription managed by its IT organization.

A TeamCloud instance is composed of two parts:

1. A user-facing [REST API](docs/API.md) that enables TeamCloud admins to manage the TeamCloud instance, and application development teams to create and manage Projects.
2. An internal [orchestration service](docs/architecture/Orchestrator.md) (sometimes referred to as "the orchestrator") that communicates with one or more [Providers](docs/Providers.md) responsible for creating and managing resources for a Project.

Together, the TeamCloud instance and its registered Providers define a template for a policy-compliant, secure, cloud development environment, which software development teams can create on-demand.

### Projects

A TeamCloud instance and its registered Providers define a template for a policy-compliant, secure, cloud development environment, which software development teams can create on-demand. In the context of TeamCloud, these cloud development environments are called Projects.
2. An internal [orchestration service](docs/Orchestrator.md) (sometimes referred to as "the orchestrator") that communicates with one or more [Providers](docs/Providers.md) responsible for creating and managing resources for a Project.

### Providers

A Provider is responsible for managing one or more resources for a Project. For example, an organization may implement an "Azure Key Vault Provider" responsible for creating a new Key Vault instance for each Project. Another example would be a "GitHub repo provider" that creates an associated source code repository for each Project.

Providers are registered with a TeamCloud instance and invoked by the Orchestrator when a Project is created or changed. Any service that implements [required REST endpoints](docs/Providers.md) can be [registered as a Provider](docs/TeamCloudYaml.md).

# Use

There are a few steps steps required to get a TeamCloud instance configured and deployed:

## Deploy the Azure Resources
#### TeamCloud Azure Resources

A TeamCloud instance is made up of the following Azure resources:

- [App Service][app-service]
- [App Configuration][app-configuration]
- [Application Insights][application-insights]
- [Event Grid][event-grid]
- [Function Apps][function-apps]
- [Storage Accounts][storage-account]
- [Key Vault][key-vault]
- [Storage Account][storage-account]

[![Deploy to Azure][azure-deploy-button]][azure-deploy]

Deploying the Azure resources is as simple as clicking the _"Deploy to Azure"_ link above and filling in a few fields.Below is a brief explanation for filling in each field, please [file an issue](issues/new?labels=docs) if you have questions or require additional help.

- **`Subscription`** Select which Azure subscription you want to use. It's okay if you only have one choice, or you don't see this option at all.
- **`Resource group`** Unless you have an existing Resource group that you know you want to use, select __Create new__ and provide a name for the new group. _(a resource group is essentially a parent folder to deploy the resources that make up the TeamCloud instance).
- **`Location`** Select the region to deploy the new resources. You want to choose a region that best describes your location (or your users location).
- **`Function App Name`** Provide a name for your app. This can be the same name as your Resource group, and will be used as the subdomain for your service endpoint. For example, if you used `superawesome`, your TeamCloud API would live at `superawesome.azurewebsites.net/api`.
- **Agree & Purchase:** Read and agree to the _TERMS AND CONDITIONS_, then click _Purchase_.

## Deploy the Code to Azure

// TODO...

## Build Locally

***Note: [deploying the Azure resources](#deploy-the-azure-resources) is required even when building and running the source code locally.***
- [Event Grid][event-grid]
- [Application Insights][application-insights]

### Development Environment
![Azure architecture diagram](docs/TeamCloud.png)

TeamCloud is built on top of Azure Functions and targets [3.x runtime version][functions-runtime-versions].
These resources are deployed using the [CLI](docs/CLI.md). After installing the CLI use `az tc deploy -h` deployment instructions.

[Azure Functions Core Tools][functions-core-tools] **version 3+** is required to build and run the code locally. Core Tools is already integrated into some development environments. See the documentation [here][functions-local-development] for guidance on setting up your environment for local development with functions.
### Projects

### local.settings.json

The [`local.settings.json`][functions-local-settings] file stores app settings, connection strings, and settings used by local development tools. Settings in the local.settings.json file are used only when you're running projects locally.
A TeamCloud instance and its registered Providers define a templates (Project Types) for a policy-compliant, secure, cloud development environment, which software development teams can create on-demand. In the context of TeamCloud, these cloud development environments are called Projects.

This file contains keys and connection strings, so it is not committed to this public repo. After cloning this repo, you'll need to create a new `local.settings.json` file in the `src` folder. The file's contents should contain the following:
### Providers

```json
{
"IsEncrypted": false,
"Values": {
"AzureCosmosDBConnection": "<Your-CosmosDB-Connection-String>",
"AzureWebJobsStorage": "<Your-WebJobs-Storage-Account-Connection-String>",
"DurableFunctionsHubStorage": "<Your-TaskHub-Storage-Account-Connection-String>",
"FUNCTIONS_WORKER_RUNTIME": "dotnet",
"AppConfigurationConnectionString": "Your-App-Configuration-Connection-String"
}
}
```
A Provider is responsible for managing one or more resources for a Project. For example, an organization may implement an "Azure Key Vault Provider" responsible for creating a new Key Vault instance for each Project. Another example would be a "GitHub repo provider" that creates an associated source code repository for each Project.

Values for these settings can be [retrieved manually][functions-get-storage]. However, if you used the _"Deploy to Azure"_ button above, each of these settings was automatically added to your Functions App's Settings and can easily be retrieved using the [portal][functions-get-settings-portal] or [CLI][functions-get-settings-cli].
Providers are registered with a TeamCloud instance and invoked by the Orchestrator when a Project is created or changed. Any service that implements required REST endpoints can be registered as a Provider using the [CLI](docs/CLI.md).

# About

Expand All @@ -109,20 +67,10 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
contact [[email protected]](mailto:[email protected]) with any additional questions or comments.

[app-service]:https://azure.microsoft.com/en-us/services/app-service/
[app-configuration]:https://azure.microsoft.com/en-us/services/app-configuration/
[function-apps]:https://azure.microsoft.com/en-us/services/functions/
[storage-account]:https://azure.microsoft.com/en-us/services/storage/
[key-vault]:https://azure.microsoft.com/en-us/services/key-vault/
[event-grid]:https://azure.microsoft.com/en-us/services/event-grid/
[application-insights]:https://azure.microsoft.com/en-us/services/monitor/

[azure-deploy]:https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2FTeamCloud%2Fmaster%2Fazuredeploy.json
[azure-deploy-button]:https://azuredeploy.net/deploybutton.svg

[functions-core-tools]:https://docs.microsoft.com/en-us/azure/azure-functions/functions-run-local
[functions-runtime-versions]:https://docs.microsoft.com/en-us/azure/azure-functions/functions-versions
[functions-local-development]:https://docs.microsoft.com/en-us/azure/azure-functions/functions-develop-local#local-development-environments
[functions-local-settings]:https://docs.microsoft.com/en-us/azure/azure-functions/functions-run-local#local-settings-file
[functions-get-storage]:https://docs.microsoft.com/en-us/azure/azure-functions/functions-run-local#get-your-storage-connection-strings
[functions-get-settings-portal]:https://docs.microsoft.com/en-us/azure/azure-functions/functions-how-to-use-azure-function-app-settings#portal
[functions-get-settings-cli]:https://docs.microsoft.com/en-us/azure/azure-functions/functions-how-to-use-azure-function-app-settings#azure-cli
3 changes: 3 additions & 0 deletions TeamCloud+Providers.code-workspace
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,9 @@
},
{
"path": "client"
},
{
"path": "docs"
}
],
"settings": {
Expand Down
106 changes: 65 additions & 41 deletions docs/API.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,78 +2,102 @@

***\*This file is incomplete. It is a work in progress and will change.\****

TeamCloud provides a user-facing REST API that enables TeamCloud admins to manage the TeamCloud instance, and application development teams to create and manage Projects.
A TeamCloud instance exposes a user-facing REST API that enables application development teams to create and manage Projects, and TeamCloud admins to manage the TeamCloud instance itself.

Organizations either use the [TeamCloud Client](Client.md) or integrate TeamCloud into existing workflows and tools by using the REST API directly.
Organizations either use the [TeamCloud CLI](CLI.md) to interface with this REST API, or integrate TeamCloud into existing workflows and tools by using the REST API directly.

This document will initially contain the high-level design for the TeamCloud API. Documentation on using the API will be added in the future.
Once deployed, TeamCloud instances provide an API explorer that can be found at **_`/swagger`_**.

## TeamCloud Admin API
Below is a summary of the REST API.

### /config/
## Projects

- Must be a User on the TeamCloud instance with the Admin role to call the TeamCloud Config API.
- **`GET` _`​/api​/projects`_** Gets all Projects.

##### GET
- **`POST` _`​/api​/projects`_** Creates a new Project.

- Returns: The [teamcloud.yaml](TeamCloudYaml.md) configuration file currently used by the TeamCloud instance

##### POST
- **`GET` _`​/api​/projects​/{projectNameOrId}`_** Gets a Project by Name or ID.

- Payload: An updated [teamcloud.yaml](TeamCloudYaml.md) configuration file to use by the TeamCloud instance
- **`DELETE` _`​/api​/projects​/{projectNameOrId}`_** Deletes a Project.

### /users/
## Project Users

- Must be a User on the TeamCloud instance with the Admin role to call the TeamCloud Users API.
- **`GET` _`​/api​/projects​/{projectId}​/users`_** Gets all Users for a Project.

##### GET
- **`POST` _`​/api​/projects​/{projectId}​/users`_** Creates a new Project User

- Returns: An array of [User](architecture/models/User.md) objects representing the TeamCloud instance's TeamCloud Users
- **`PUT` _`​/api​/projects​/{projectId}​/users`_** Updates an existing Project User.

##### POST
- **`GET` _`​/api​/projects​/{projectId}​/users​/{userNameOrId}`_** Gets a Project User by ID or email address.

- Payload: An array of [UserDefinition](architecture/models/User.md#userdefinition) objects representing Users to add to the TeamCloud instance
- **`DELETE` _`​/api​/projects​/{projectId}​/users​/{userNameOrId}`_** Deletes an existing Project User.

##### PUT
## Project Tags

- Payload: An array of [UserDefinition](architecture/models/User.md#userdefinition) objects representing updated or additional information for existing Users on the TeamCloud instance
- **`GET` _`​/api​/projects​/{projectId}​/tags`_** Gets all Tags for a Project.

##### DELETE
- **`POST` _`​/api​/projects​/{projectId}​/tags`_** Creates a new Project Tag.

- Payload: An array of strings representing the email addresses of Users to be removed from the TeamCloud instance
- **`PUT` _`​/api​/projects​/{projectId}​/tags`_** Updates an existing Project Tag.

### /projects/
- **`GET` _`​/api​/projects​/{projectId}​/tags​/{tagKey}`_** Gets a Project Tag by Key.

##### GET
- **`DELETE` _`​/api​/projects​/{projectId}​/tags​/{tagKey}`_** Deletes an existing Project Tag.

- Must be a User on the TeamCloud instance with the Admin role to call this API
- Returns: An array of [Project](architecture/models/Project.md) objects representing the TeamCloud instance's Projects
## Providers

##### POST
- **`GET` _`​/api​/providers`_** Gets all Providers.

- Must be a User on the TeamCloud instance with either the Admin or Creator role to call this API
- Payload: A [ProjectDefinition](architecture/models/Project.md#projectdefinition) objects representing Users to add to the TeamCloud instance
- **`POST` _`​/api​/providers`_** Creates a new Provider.

##### DELETE
- **`PUT` _`​/api​/providers`_** Updates an existing Provider.

- Must be a User on the TeamCloud instance with the Admin role, or with Creator role and have the Owner role on the Project to call this API
- Payload: A string representing the Project ID of the Project to be removed from the TeamCloud instance
- **`GET` _`​/api​/providers​/{providerId}`_** Gets a Provider by ID.

### /providers/
- **`DELETE` _`​/api​/providers​/{providerId}`_** Deletes an existing Provider.

- Adding, updating, and removing Providers is done through the Config API.
- Must be a User on the TeamCloud instance with the Admin role to call the TeamCloud Providers API.
## Project Types

##### GET
- **`GET` _`​/api​/projectTypes`_** Gets all Project Types.

- Returns: An array of [Provider](architecture/models/Provider.md) objects representing the TeamCloud instance's registered Providers
- **`POST` _`​/api​/projectTypes`_** Creates a new Project Type.

## TeamCloud Project API
- **`PUT` _`​/api​/projectTypes`_** Updates an existing Project Type.

### /projects/{projectId}/tags/
- **`GET` _`​/api​/projectTypes​/{projectTypeId}`_** Gets a Project Type by ID.

### /projects/{projectId}/users/
- **`DELETE` _`​/api​/projectTypes​/{projectTypeId}`_** Deletes a Project Type.

### /projects/{projectId}/providers/
## TeamCloud Users

### /projects/{projectId}/providers/{providerId}
- **`GET` _`​/api​/users`_** Gets all TeamCloud Users.

- **`POST` _`​/api​/users`_** Creates a new TeamCloud User.

- **`PUT` _`​/api​/users`_** Updates an existing TeamCloud User.

- **`GET` _`​/api​/users​/{userNameOrId}`_** Gets a TeamCloud User by ID or email address.

- **`DELETE` _`​/api​/users​/{userNameOrId}`_** Deletes an existing TeamCloud User.

## TeamCloud Tags

- **`GET` _`​/api​/tags`_** Gets all Tags for a TeamCloud Instance.

- **`POST` _`​/api​/tags`_** Creates a new TeamCloud Tag.

- **`PUT` _`​/api​/tags`_** Updates an existing TeamCloud Tag.

- **`GET` _`​/api​/tags​/{tagKey}`_** Gets a TeamCloud Tag by Key.

- **`DELETE` _`​/api​/tags​/{tagKey}`_** Deletes an existing TeamCloud Tag.

## Status

- **`GET` _`​/api​/status​/{trackingId}`_** Gets the status of a long-running operation.

- **`GET` _`​/api​/projects​/{projectId}​/status​/{trackingId}`_** Gets the status of a long-running operation.

## Admin

- **`POST` _`​/api​/admin​/users`_** Creates a new TeamCloud User as an Admin.
3 changes: 0 additions & 3 deletions docs/Assumptions.md
View file

This file was deleted.

13 changes: 0 additions & 13 deletions docs/Backlog.md
View file

This file was deleted.

49 changes: 49 additions & 0 deletions docs/CLI.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# TeamCloud CLI

***\*This file is incomplete. It is a work in progress and will change.\****

The TeamCloud CLI is an [extension](https://docs.microsoft.com/en-us/cli/azure/azure-cli-extensions-overview?view=azure-cli-latest) for the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/?view=azure-cli-latest). It can be used by application development teams to create and manage Projects, and by TeamCloud admins to create new TeamCloud instances or manage existing instances.

## Install

To install the Azure CLI TeamCloud extension, simply run the following command:

```sh
az extension add --source https://github.com/microsoft/TeamCloud/releases/download/v0.1.274/tc-0.2.2-py2.py3-none-any.whl -y
```

### Update

To update Azure CLI TeamCloud extension, you must first remove the currently installed version of the extension:

```sh
az extension remove -n tc
```

Then run the install command with the location of the updated extension version:

```sh
az extension add --source https://github.com/microsoft/TeamCloud/releases/download/v0.1.274/tc-0.2.2-py2.py3-none-any.whl -y
```

## Local Development

To use the Azure CLI TeamCloud extension with a locally running TeamCloud instance, first set the default base url to your localhost TeamCloud API endpoint:

```sh
az configure -d tc-base-url=https://localhost:5001
```

Next, you must temporarily disable Azure CLI's connection verification:

macOS or Linux

```sh
export AZURE_CLI_DISABLE_CONNECTION_VERIFICATION=1
```

Windows

```cmd
set AZURE_CLI_DISABLE_CONNECTION_VERIFICATION=1
```
Loading

0 comments on commit ba5354e

Please sign in to comment.