Add documentation site content (#92)

* Added initial documentation for pages site
cello-proj · Sep 15, 2021 · 559368a · 559368a
1 parent 7527e85
commit 559368a
Show file tree

Hide file tree

Showing 22 changed files with 312 additions and 7 deletions.
diff --git a/README.md b/README.md
@@ -23,5 +23,5 @@ including CDK, Terraform and Cloud Formation via GitOps.
 
 * [Get Started Here](/docs/quickstart.md)
 * [Architecture](/docs/architecture.md)
-* [API](/docs/api.md)
-* [Development Setup](/docs/development.md)
+* [API](/docs/developers/api.md)
+* [Development Setup](/docs/developers/development-env.md)
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -1,4 +1,4 @@
-![Architecture](/pictures/architecure.png)
+![Architecture](./assets/architecure.png)
 
 ## Definitions
 
@@ -30,7 +30,7 @@ environment variable which is read by the service at startup. The admin token is
 project. User tokens do not have the ability to manage the associated project or targets. User tokens have the format **PROVIDER:USER:SECRET**. User tokens are passed in the **Authorization** header to
 the service.
 
-* **Credential Tokens** Is used to obtain target credentials. Credential tokens are short lived and limited use tokens. They are generated and passed to the workflow during an operation. The token is then exchanged (via the credential provider) for target credentials (AWS credentials, etc). Credential tokens have a format based on the provider and should be considered opaque (for example vault **s.ABCDEFGHIJKLMNOPQRSTUVWXYZ**). Credentials tokens are
+* **Credential Tokens** Are used to obtain target credentials. Credential tokens are short lived and limited use tokens. They are generated and passed to the workflow during an operation. The token is then exchanged (via the credential provider) for target credentials (AWS credentials, etc). Credential tokens have a format based on the provider and should be considered opaque (for example vault **s.ABCDEFGHIJKLMNOPQRSTUVWXYZ**). Credentials tokens are
 passed from the credential provider to the service and then on to the workflow.
 
 ## State
@@ -53,13 +53,13 @@ Additionally you can define your own frameworks in **argo-cloudops.yaml**.
 
 ## Workflow
 
-Argo CloudOps uses Argo Workflows as it's workflow engine. To execute the provided command, an Argo workflow
+Argo CloudOps uses [Argo Workflows](https://argoproj.github.io/argo-workflows/) as its workflow engine. To execute the provided command, an Argo workflow
 is submitted by the service. Ordinary users should not need to access Argo workflows directly.  Workflows
 are stored as Argo Workflow Templates. Currently there is one generic workflow for all commands which
 performs one step which executes the image provided with the command, arguments and environment variables.
 
 ## Config
 
 The config file contains the commands executed by different frameworks.  The example config in
-[/examples/argo-cloudops.yaml](/examples/argo-cloudops.yaml) contains the default commands to
+[argo-cloudops.yaml](https://github.com/argoproj-labs/argo-cloudops/blob/main/argo-cloudops.yaml) contains the default commands to
 run **cdk** and **terraform**.
diff --git a/pictures/architecure.png → docs/assets/architecure.png b/pictures/architecure.png → docs/assets/architecure.png
diff --git a/docs/cli/argo-cloudops.md b/docs/cli/argo-cloudops.md
@@ -0,0 +1,32 @@
+## argo-cloudops
+
+argo-cloudops is the command line interface to Argo CloudOps
+
+```
+argo-cloudops [command]
+```
+
+### Options
+
+```
+Available Commands:
+  completion  generate the autocompletion script for the specified shell
+  diff        Diff a project target using a manifest in git
+  get         Gets status of workflow
+  help        Help about any command
+  list        List workflow executions for a given project and target
+  logs        Gets logs from a workflow
+  sync        Syncs a project target using a manifest in git
+  version     Reports the version
+  workflow    Creates a workflow execution with provided arguments
+
+Flags:
+  -h, --help   help for argo-cloudops
+```
+
+### SEE ALSO
+
+* [argo-cloudops logs](argo-cloudops_logs.md) - gets logs from a workflow
+
+
+
diff --git a/docs/cli/argo-cloudops_diff.md b/docs/cli/argo-cloudops_diff.md
@@ -0,0 +1,16 @@
+## argo-cloudops diff
+Diff a project target using a manifest in git
+
+```
+  argo-cloudops diff [flags]
+```
+
+### Flags
+
+```
+  -h, --help                  help for diff
+  -p, --path string           Path to manifest within git repository
+  -n, --project_name string   Name of project
+  -s, --sha string            Commit sha to use when creating workflow through git
+  -t, --target string         Name of target
+```
diff --git a/docs/cli/argo-cloudops_get.md b/docs/cli/argo-cloudops_get.md
@@ -0,0 +1,12 @@
+## argo-cloudops get
+Gets status of workflow
+
+```
+  argo-cloudops get [workflow name] [flags]
+```
+
+### Flags
+
+```
+  -h, --help                  help for get
+```
diff --git a/docs/cli/argo-cloudops_list.md b/docs/cli/argo-cloudops_list.md
@@ -0,0 +1,14 @@
+## argo-cloudops list
+List workflow executions for a given project and target
+
+```
+  argo-cloudops list [flags]
+```
+
+### Flags
+
+```
+  -h, --help                  help for list
+  -n, --project_name string   Name of project
+  -t, --target_name string    Name of target
+```
diff --git a/docs/cli/argo-cloudops_logs.md b/docs/cli/argo-cloudops_logs.md
@@ -0,0 +1,14 @@
+## argo-cloudops logs
+
+Gets logs from a workflow
+
+```
+  argo-cloudops logs [workflow name] [flags]
+```
+
+### Flags
+
+```
+  -f, --follow   Follow workflow logs and stream to standard out until workflow is complete
+  -h, --help     help for logs
+```
diff --git a/docs/cli/argo-cloudops_sync.md b/docs/cli/argo-cloudops_sync.md
@@ -0,0 +1,17 @@
+## argo-cloudops sync
+
+Syncs a project target using a manifest in git
+
+```
+  argo-cloudops sync [flags]
+```
+
+### Flags
+
+```
+  -h, --help                  help for sync
+  -p, --path string           Path to manifest within git repository
+  -n, --project_name string   Name of project
+  -s, --sha string            Commit sha to use when creating workflow through git
+  -t, --target string         Name of target
+```
diff --git a/docs/cli/argo-cloudops_workflow.md b/docs/cli/argo-cloudops_workflow.md
@@ -0,0 +1,20 @@
+## argo-cloudops workflow
+Creates a workflow execution with provided arguments
+
+```
+  argo-cloudops workflow [flags]
+```
+
+### Flags
+
+```
+  -a, --arguments string                CSV string of equals separated arguments to pass to command (-a Arg1=ValueA,Arg2=ValueB).
+  -e, --environment_variables string    CSV string of equals separated environment variable key value pairs (-e Key1=ValueA,Key2=ValueB)
+  -f, --framework string                Framework to execute
+  -h, --help                            help for workflow
+  -p, --parameters string               CSV string of equals separated parameters name and value (-p Param1=ValueA,Param2=ValueB).
+  -n, --project_name string             Name of project
+  -t, --target string                   Name of target
+      --type string                     Workflow type to execute
+  -w, --workflow_template_name string   Name of the workflow template
+```
diff --git a/docs/developers/CONTRIBUTING.md b/docs/developers/CONTRIBUTING.md
@@ -0,0 +1,24 @@
+# Contributing
+
+## How To Provide Feedback
+
+Please [raise an issue in Github](https://github.com/argoproj-labs/argo-cloudops/issues).
+
+## Code of Conduct
+
+See [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
+
+## How To Contribute
+
+We're always looking for contributors.
+
+* Documentation - something missing or unclear? Please submit a pull request!
+* Code contribution - investigate an [issue](https://github.com/argoproj-labs/argo-cloudops/issues)
+
+### Local Development Environment
+
+To run Argo CloudOps locally for [development](development-env.md).
+
+### Test Policy
+
+Changes without unit tests are unlikely to be accepted. 
diff --git a/docs/api.md → docs/developers/api.md b/docs/api.md → docs/developers/api.md
diff --git a/docs/development.md → docs/developers/development-env.md b/docs/development.md → docs/developers/development-env.md
@@ -134,4 +134,4 @@ project and target. This returns the **ARGO_CLOUDOPS_USER_TOKEN** for the new pr
     # Get the status / logs
     ./build/argo-cloudops get $TERRAFORM_WORKFLOW_NAME
     ./build/argo-cloudops logs $TERRAFORM_WORKFLOW_NAME
-    ```
+    ```
diff --git a/docs/releasing.md → docs/developers/releasing.md b/docs/releasing.md → docs/developers/releasing.md
diff --git a/docs/developers/static-code-analysis.md b/docs/developers/static-code-analysis.md
@@ -0,0 +1,7 @@
+# Static Code Analysis
+
+We use the following static code analysis tools:
+
+* [golangci-lint](https://github.com/argoproj-labs/argo-cloudops/blob/main/.golangci.yaml) for compile time linting
+
+This is run on each pull request.
diff --git a/docs/faq.md b/docs/faq.md
@@ -0,0 +1,7 @@
+# FAQ
+
+> Argo CloudOps server returns "INTERNAL ERROR" when following logs
+
+This happens when a deployment executes for a long time. Just reissue the logs command to retry. Team is tracking an [issue](https://github.com/argoproj-labs/argo-cloudops/issues/93) to resolve
+
+
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,23 @@
+[![build](https://github.com/argoproj-labs/argo-cloudops/actions/workflows/build.yaml/badge.svg)](https://github.com/argoproj-labs/argo-cloudops/actions/workflows/build.yaml)
+
+
+## What Is Argo CloudOps?
+
+Argo CloudOps is a service for running infrastructure as code software tools
+including CDK, Terraform and Cloud Formation via GitOps.
+
+* Separate build and deployment
+* Isolate cloud credentials
+* Separate access by project and targets
+
+## Why Argo CloudOps?
+
+* GitOps opperating model
+* Multi cloud support (AWS, GCP, etc)
+* Multi framework support (CDK, Terraform, etc)
+* Pluggable components (Workflows, Frameworks, Credentials Providers, etc)
+
+# Argo Documentation
+
+### Getting Started
+For set-up information and running your first Workflows, please see our [Getting Started](quickstart.md) guide.
diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -0,0 +1,3 @@
+# Roadmap
+
+
diff --git a/docs/users/cli.md b/docs/users/cli.md
@@ -0,0 +1,20 @@
+# CLI
+
+The CLI allows to (amongst other things) manage projects, sync, watch, and list deployments, e.g.: 
+
+```sh
+WFNAME=`argo-cloudops sync -n project1 -t target1 -p git_path -s git_sha`
+argo-cloudops logs $WFNAME -f    
+```   
+
+## Reference
+
+You can find [detailed reference here](/cli/argo-cloudops)
+
+## Help
+
+Most help topics are provided by built-in help:
+
+```
+argo-cloudops --help
+```
diff --git a/docs/users/coreconcepts.md b/docs/users/coreconcepts.md
@@ -0,0 +1,29 @@
+# Core Concepts
+
+This page serves as additional information in addition to the [Argo CloudOps Architecture](/architecture).
+
+
+## Project
+
+A project is a logical collection of all deployment targets.
+
+### Properties
+| Name            | Description                                                                                                   |
+|-----------------|---------------------------------------------------------------------------------------------------------------|
+| name            | name for the project                                                                                          |
+| repository      | link to the github repository with [all project manifests](https://github.com/argoproj-labs/argo-cloudops/blob/main/manifests/cdk_manifest.yaml). Should match the auth method being used (HTTPS, SSH). |
+
+## Target
+
+A target represents a unique deployment for a project. It contains information related to cloud account access mechanism & policies for scoping permissions. Currently the only type of cloud account supported is AWS.
+
+### Properties
+
+| Name            | Description                                                           |
+|-----------------|-----------------------------------------------------------------------|
+| credential_type | the type of credential mechanis to use. Currently only "assumed_role" |
+| role_arn        | the role that the service assumes                                     |
+| policy_arns     | A list of AWS policy ARNs to use for permissions scope limiting       |
+| policy_document | An inline document to scope down permissions                          |
+
+
diff --git a/docs/users/envvars.md b/docs/users/envvars.md
@@ -0,0 +1,23 @@
+# Environment Variables
+
+Argo CloudOps uses a number of environment variables for configuration. In addition to the table below, you can review the [start_local.sh](https://github.com/argoproj-labs/argo-cloudops/blob/main/scripts/start_local.sh) script for examples.
+
+| Name                                       | Description                                                                                                                                     |
+|--------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
+| ARGO_CLOUDOPS_ADMIN_SECRET                 | Secret for the Argo CloudOps API                                                                                                                |
+| VAULT_ROLE                                 | Role for accessing Vault API                                                                                                                                 |
+| VAULT_SECRET                               | Secret for access Vault instance                                                                                                                |
+| VAULT_ADDR                                 | Endpoint for the Vault instance                                                                                                                 |
+| ARGO_ADDR                                  | Argo Endpoint                                                                                                                                   |
+| ARGO_CLOUDOPS_WORKFLOW_EXECUTION_NAMESPACE | Namespace to use to execute the deployments in Argo Workflows (Default: argo)                                                                   |
+| ARGO_CLOUDOPS_CONFIG                       | File that contains argo cloudops command configuration. [Example](https://github.com/argoproj-labs/argo-cloudops/blob/main/argo-cloudops.yaml) |
+| SSH_PEM_FILE                               | PEM file to use for GITHUB access authentication                                                                                                |
+| ARGO_CLOUDOPS_GIT_AUTH_METHOD              | A value of SSH or HTTPS depending on which authentication method prefered.                                                                      |
+| ARGO_CLOUDOPS_GIT_HTTPS_USER               | User name for GITHUB access authentication via HTTPS.                                                                                           |
+| ARGO_CLOUDOPS_GIT_HTTPS_PASS               | Password for GITHUB access authentication via HTTPS.                                                                                            |
+| ARGO_CLOUDOPS_DB_HOST                      | Database Host                                                                                                                                   |
+| ARGO_CLOUDOPS_DB_USER                      | Database User                                                                                                                                   |
+| ARGO_CLOUDOPS_DB_PASSWORD                  | Database Password                                                                                                                               |
+| ARGO_CLOUDOPS_DB_NAME                      | Database name                                                                                                                                   |
+| ARGO_CLOUDOPS_LOG_LEVEL                    | The configured log level for Argo CloudOps service (Default: Info)                                                                              |
+| ARGO_CLOUDOPS_PORT                         | Port which the Argo CloudOps service listens (Default: 8443)                                                                                    |
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,44 @@
+site_name: Argo CloudOps - The engine for cloud deployments
+repo_url: https://github.com/argoproj-labs/argo-cloudops
+strict: true
+theme:
+  name: material
+  palette:
+    primary: blue
+  font:
+    text: Work Sans
+markdown_extensions:
+  - codehilite
+  - admonition
+  - pymdownx.superfences
+  - pymdownx.details
+  - toc:
+      permalink: true
+nav:
+  - Overview: index.md
+  - Architecture: architecture.md
+  - Quick Start: quickstart.md
+  - User Guide:
+    - Beginner: 
+      - Core Concepts: users/coreconcepts.md
+      - CLI: users/cli.md
+    - Environment Variables: users/envvars.md
+    - Examples: https://github.com/argoproj-labs/argo-cloudops/blob/master/examples/README.md
+    - CLI Reference:
+        - argo-cloudops: cli/argo-cloudops.md
+        - argo-cloudops sync: cli/argo-cloudops_sync.md
+        - argo-cloudops diff: cli/argo-cloudops_diff.md
+        - argo-cloudops get: cli/argo-cloudops_get.md
+        - argo-cloudops list: cli/argo-cloudops_list.md
+        - argo-cloudops workflow: cli/argo-cloudops_workflow.md
+        - argo-cloudops logs: cli/argo-cloudops_logs.md
+  - Developer Guide:
+    - Local Development Environment: developers/development-env.md
+    - Contributing: developers/CONTRIBUTING.md
+    - Static Code Analysis: developers/static-code-analysis.md
+    - API: developers/api.md
+    - Releasing: developers/releasing.md
+  - FAQ: faq.md
+  - Releases ⧉: https://github.com/argoproj-labs/argo-cloudops/releases
+  - Roadmap: roadmap.md
+  - Appendix: appendix.md