Skip to content

Commit 559368a

Browse files
jk-intuitjk-intuit
authored
Add documentation site content (#92)
* Added initial documentation for pages site
1 parent 7527e85 commit 559368a

22 files changed

+312
-7
lines changed

‎README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,5 +23,5 @@ including CDK, Terraform and Cloud Formation via GitOps.
2323

2424
* [Get Started Here](/docs/quickstart.md)
2525
* [Architecture](/docs/architecture.md)
26-
* [API](/docs/api.md)
27-
* [Development Setup](/docs/development.md)
26+
* [API](/docs/developers/api.md)
27+
* [Development Setup](/docs/developers/development-env.md)

‎docs/architecture.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
![Architecture](/pictures/architecure.png)
1+
![Architecture](./assets/architecure.png)
22

33
## Definitions
44

@@ -30,7 +30,7 @@ environment variable which is read by the service at startup. The admin token is
3030
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
3131
the service.
3232

33-
* **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
33+
* **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
3434
passed from the credential provider to the service and then on to the workflow.
3535

3636
## State
@@ -53,13 +53,13 @@ Additionally you can define your own frameworks in **argo-cloudops.yaml**.
5353

5454
## Workflow
5555

56-
Argo CloudOps uses Argo Workflows as it's workflow engine. To execute the provided command, an Argo workflow
56+
Argo CloudOps uses [Argo Workflows](https://argoproj.github.io/argo-workflows/) as its workflow engine. To execute the provided command, an Argo workflow
5757
is submitted by the service. Ordinary users should not need to access Argo workflows directly. Workflows
5858
are stored as Argo Workflow Templates. Currently there is one generic workflow for all commands which
5959
performs one step which executes the image provided with the command, arguments and environment variables.
6060

6161
## Config
6262

6363
The config file contains the commands executed by different frameworks. The example config in
64-
[/examples/argo-cloudops.yaml](/examples/argo-cloudops.yaml) contains the default commands to
64+
[argo-cloudops.yaml](https://github.com/argoproj-labs/argo-cloudops/blob/main/argo-cloudops.yaml) contains the default commands to
6565
run **cdk** and **terraform**.

‎pictures/architecure.png renamed to ‎docs/assets/architecure.png

File renamed without changes.

‎docs/cli/argo-cloudops.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
## argo-cloudops
2+
3+
argo-cloudops is the command line interface to Argo CloudOps
4+
5+
```
6+
argo-cloudops [command]
7+
```
8+
9+
### Options
10+
11+
```
12+
Available Commands:
13+
completion generate the autocompletion script for the specified shell
14+
diff Diff a project target using a manifest in git
15+
get Gets status of workflow
16+
help Help about any command
17+
list List workflow executions for a given project and target
18+
logs Gets logs from a workflow
19+
sync Syncs a project target using a manifest in git
20+
version Reports the version
21+
workflow Creates a workflow execution with provided arguments
22+
23+
Flags:
24+
-h, --help help for argo-cloudops
25+
```
26+
27+
### SEE ALSO
28+
29+
* [argo-cloudops logs](argo-cloudops_logs.md) - gets logs from a workflow
30+
31+
32+

‎docs/cli/argo-cloudops_diff.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
## argo-cloudops diff
2+
Diff a project target using a manifest in git
3+
4+
```
5+
argo-cloudops diff [flags]
6+
```
7+
8+
### Flags
9+
10+
```
11+
-h, --help help for diff
12+
-p, --path string Path to manifest within git repository
13+
-n, --project_name string Name of project
14+
-s, --sha string Commit sha to use when creating workflow through git
15+
-t, --target string Name of target
16+
```

‎docs/cli/argo-cloudops_get.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
## argo-cloudops get
2+
Gets status of workflow
3+
4+
```
5+
argo-cloudops get [workflow name] [flags]
6+
```
7+
8+
### Flags
9+
10+
```
11+
-h, --help help for get
12+
```

‎docs/cli/argo-cloudops_list.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
## argo-cloudops list
2+
List workflow executions for a given project and target
3+
4+
```
5+
argo-cloudops list [flags]
6+
```
7+
8+
### Flags
9+
10+
```
11+
-h, --help help for list
12+
-n, --project_name string Name of project
13+
-t, --target_name string Name of target
14+
```

‎docs/cli/argo-cloudops_logs.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
## argo-cloudops logs
2+
3+
Gets logs from a workflow
4+
5+
```
6+
argo-cloudops logs [workflow name] [flags]
7+
```
8+
9+
### Flags
10+
11+
```
12+
-f, --follow Follow workflow logs and stream to standard out until workflow is complete
13+
-h, --help help for logs
14+
```

‎docs/cli/argo-cloudops_sync.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
## argo-cloudops sync
2+
3+
Syncs a project target using a manifest in git
4+
5+
```
6+
argo-cloudops sync [flags]
7+
```
8+
9+
### Flags
10+
11+
```
12+
-h, --help help for sync
13+
-p, --path string Path to manifest within git repository
14+
-n, --project_name string Name of project
15+
-s, --sha string Commit sha to use when creating workflow through git
16+
-t, --target string Name of target
17+
```

‎docs/cli/argo-cloudops_workflow.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
## argo-cloudops workflow
2+
Creates a workflow execution with provided arguments
3+
4+
```
5+
argo-cloudops workflow [flags]
6+
```
7+
8+
### Flags
9+
10+
```
11+
-a, --arguments string CSV string of equals separated arguments to pass to command (-a Arg1=ValueA,Arg2=ValueB).
12+
-e, --environment_variables string CSV string of equals separated environment variable key value pairs (-e Key1=ValueA,Key2=ValueB)
13+
-f, --framework string Framework to execute
14+
-h, --help help for workflow
15+
-p, --parameters string CSV string of equals separated parameters name and value (-p Param1=ValueA,Param2=ValueB).
16+
-n, --project_name string Name of project
17+
-t, --target string Name of target
18+
--type string Workflow type to execute
19+
-w, --workflow_template_name string Name of the workflow template
20+
```

‎docs/developers/CONTRIBUTING.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Contributing
2+
3+
## How To Provide Feedback
4+
5+
Please [raise an issue in Github](https://github.com/argoproj-labs/argo-cloudops/issues).
6+
7+
## Code of Conduct
8+
9+
See [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
10+
11+
## How To Contribute
12+
13+
We're always looking for contributors.
14+
15+
* Documentation - something missing or unclear? Please submit a pull request!
16+
* Code contribution - investigate an [issue](https://github.com/argoproj-labs/argo-cloudops/issues)
17+
18+
### Local Development Environment
19+
20+
To run Argo CloudOps locally for [development](development-env.md).
21+
22+
### Test Policy
23+
24+
Changes without unit tests are unlikely to be accepted.

‎docs/api.md renamed to ‎docs/developers/api.md

File renamed without changes.

‎docs/development.md renamed to ‎docs/developers/development-env.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -134,4 +134,4 @@ project and target. This returns the **ARGO_CLOUDOPS_USER_TOKEN** for the new pr
134134
# Get the status / logs
135135
./build/argo-cloudops get $TERRAFORM_WORKFLOW_NAME
136136
./build/argo-cloudops logs $TERRAFORM_WORKFLOW_NAME
137-
```
137+
```

‎docs/releasing.md renamed to ‎docs/developers/releasing.md

File renamed without changes.

‎docs/developers/static-code-analysis.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Static Code Analysis
2+
3+
We use the following static code analysis tools:
4+
5+
* [golangci-lint](https://github.com/argoproj-labs/argo-cloudops/blob/main/.golangci.yaml) for compile time linting
6+
7+
This is run on each pull request.

‎docs/faq.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# FAQ
2+
3+
> Argo CloudOps server returns "INTERNAL ERROR" when following logs
4+
5+
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
6+
7+

‎docs/index.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
[![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)
2+
3+
4+
## What Is Argo CloudOps?
5+
6+
Argo CloudOps is a service for running infrastructure as code software tools
7+
including CDK, Terraform and Cloud Formation via GitOps.
8+
9+
* Separate build and deployment
10+
* Isolate cloud credentials
11+
* Separate access by project and targets
12+
13+
## Why Argo CloudOps?
14+
15+
* GitOps opperating model
16+
* Multi cloud support (AWS, GCP, etc)
17+
* Multi framework support (CDK, Terraform, etc)
18+
* Pluggable components (Workflows, Frameworks, Credentials Providers, etc)
19+
20+
# Argo Documentation
21+
22+
### Getting Started
23+
For set-up information and running your first Workflows, please see our [Getting Started](quickstart.md) guide.

‎docs/roadmap.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Roadmap
2+
3+

‎docs/users/cli.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# CLI
2+
3+
The CLI allows to (amongst other things) manage projects, sync, watch, and list deployments, e.g.:
4+
5+
```sh
6+
WFNAME=`argo-cloudops sync -n project1 -t target1 -p git_path -s git_sha`
7+
argo-cloudops logs $WFNAME -f
8+
```
9+
10+
## Reference
11+
12+
You can find [detailed reference here](/cli/argo-cloudops)
13+
14+
## Help
15+
16+
Most help topics are provided by built-in help:
17+
18+
```
19+
argo-cloudops --help
20+
```

‎docs/users/coreconcepts.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Core Concepts
2+
3+
This page serves as additional information in addition to the [Argo CloudOps Architecture](/architecture).
4+
5+
6+
## Project
7+
8+
A project is a logical collection of all deployment targets.
9+
10+
### Properties
11+
| Name | Description |
12+
|-----------------|---------------------------------------------------------------------------------------------------------------|
13+
| name | name for the project |
14+
| 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). |
15+
16+
## Target
17+
18+
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.
19+
20+
### Properties
21+
22+
| Name | Description |
23+
|-----------------|-----------------------------------------------------------------------|
24+
| credential_type | the type of credential mechanis to use. Currently only "assumed_role" |
25+
| role_arn | the role that the service assumes |
26+
| policy_arns | A list of AWS policy ARNs to use for permissions scope limiting |
27+
| policy_document | An inline document to scope down permissions |
28+
29+

‎docs/users/envvars.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Environment Variables
2+
3+
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.
4+
5+
| Name | Description |
6+
|--------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
7+
| ARGO_CLOUDOPS_ADMIN_SECRET | Secret for the Argo CloudOps API |
8+
| VAULT_ROLE | Role for accessing Vault API |
9+
| VAULT_SECRET | Secret for access Vault instance |
10+
| VAULT_ADDR | Endpoint for the Vault instance |
11+
| ARGO_ADDR | Argo Endpoint |
12+
| ARGO_CLOUDOPS_WORKFLOW_EXECUTION_NAMESPACE | Namespace to use to execute the deployments in Argo Workflows (Default: argo) |
13+
| ARGO_CLOUDOPS_CONFIG | File that contains argo cloudops command configuration. [Example](https://github.com/argoproj-labs/argo-cloudops/blob/main/argo-cloudops.yaml) |
14+
| SSH_PEM_FILE | PEM file to use for GITHUB access authentication |
15+
| ARGO_CLOUDOPS_GIT_AUTH_METHOD | A value of SSH or HTTPS depending on which authentication method prefered. |
16+
| ARGO_CLOUDOPS_GIT_HTTPS_USER | User name for GITHUB access authentication via HTTPS. |
17+
| ARGO_CLOUDOPS_GIT_HTTPS_PASS | Password for GITHUB access authentication via HTTPS. |
18+
| ARGO_CLOUDOPS_DB_HOST | Database Host |
19+
| ARGO_CLOUDOPS_DB_USER | Database User |
20+
| ARGO_CLOUDOPS_DB_PASSWORD | Database Password |
21+
| ARGO_CLOUDOPS_DB_NAME | Database name |
22+
| ARGO_CLOUDOPS_LOG_LEVEL | The configured log level for Argo CloudOps service (Default: Info) |
23+
| ARGO_CLOUDOPS_PORT | Port which the Argo CloudOps service listens (Default: 8443) |

‎mkdocs.yml

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
site_name: Argo CloudOps - The engine for cloud deployments
2+
repo_url: https://github.com/argoproj-labs/argo-cloudops
3+
strict: true
4+
theme:
5+
name: material
6+
palette:
7+
primary: blue
8+
font:
9+
text: Work Sans
10+
markdown_extensions:
11+
- codehilite
12+
- admonition
13+
- pymdownx.superfences
14+
- pymdownx.details
15+
- toc:
16+
permalink: true
17+
nav:
18+
- Overview: index.md
19+
- Architecture: architecture.md
20+
- Quick Start: quickstart.md
21+
- User Guide:
22+
- Beginner:
23+
- Core Concepts: users/coreconcepts.md
24+
- CLI: users/cli.md
25+
- Environment Variables: users/envvars.md
26+
- Examples: https://github.com/argoproj-labs/argo-cloudops/blob/master/examples/README.md
27+
- CLI Reference:
28+
- argo-cloudops: cli/argo-cloudops.md
29+
- argo-cloudops sync: cli/argo-cloudops_sync.md
30+
- argo-cloudops diff: cli/argo-cloudops_diff.md
31+
- argo-cloudops get: cli/argo-cloudops_get.md
32+
- argo-cloudops list: cli/argo-cloudops_list.md
33+
- argo-cloudops workflow: cli/argo-cloudops_workflow.md
34+
- argo-cloudops logs: cli/argo-cloudops_logs.md
35+
- Developer Guide:
36+
- Local Development Environment: developers/development-env.md
37+
- Contributing: developers/CONTRIBUTING.md
38+
- Static Code Analysis: developers/static-code-analysis.md
39+
- API: developers/api.md
40+
- Releasing: developers/releasing.md
41+
- FAQ: faq.md
42+
- Releases ⧉: https://github.com/argoproj-labs/argo-cloudops/releases
43+
- Roadmap: roadmap.md
44+
- Appendix: appendix.md

0 commit comments

Comments
 (0)