Skip to content

Commit 5f65cf9

Browse files
nandajavarmanandajavarma
committed
Improve the usage docs
1 parent 8f7db1d commit 5f65cf9

File tree

2 files changed

+75
-48
lines changed

2 files changed

+75
-48
lines changed

‎gitpod-network-check/README.md

Lines changed: 75 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -2,49 +2,78 @@
22

33
A CLI to check if your network setup is suitable for the installation of Gitpod.
44

5-
## How to use
6-
7-
1. In order to perform a network check create a config filed called gitpod-network-check.yaml file that needs to be located in the same directory as the gitpod-network-check binary. Alternatively you can use the `--config` option to specify the config file. The config file needs to contain the region and the subnets that you want to use for your Gitpod installation.
8-
9-
```yaml
10-
log-level: debug # Options: debug, info, warning, error
11-
region: eu-central-1
12-
main-subnets: subnet-0554e84f033a64c56, subnet-08584621e7754e505, subnet-094c6fd68aea493b7
13-
pod-subnets: subnet-028d11dce93b8eefc, subnet-04ec8257d95c434b7,subnet-00a83550ce709f39c
14-
```
15-
16-
2. Get the AWS credentials of the account where you want to install Gitpod and set them as environment variables
17-
18-
3. Run `gitpod-network-check diagnose`. The expected output should look similar to this.
19-
20-
```
21-
INFO[0000] ✅ Main Subnets are valid
22-
INFO[0000] ✅ Pod Subnets are valid
23-
INFO[0000] ℹ️ Checking prerequisites
24-
INFO[0000] ✅ VPC endpoint com.amazonaws.eu-central-1.ec2messages is configured
25-
INFO[0000] ✅ VPC endpoint com.amazonaws.eu-central-1.ssm is configured
26-
INFO[0000] ✅ VPC endpoint com.amazonaws.eu-central-1.ssmmessages is configured
27-
INFO[0001] ℹ️ Launching EC2 instance in a Main subnet
28-
INFO[0007] ℹ️ Launching EC2 instance in a Pod subnet
29-
INFO[0009] ℹ️ Waiting for EC2 instances to become ready (can take up to 2 minutes)
30-
INFO[0167] ✅ EC2 Instances are now running successfully
31-
INFO[0167] ℹ️ Connecting to SSM...
32-
INFO[0175] ℹ️ Checking if the required AWS Services can be reached from the ec2 instances
33-
INFO[0178] ✅ Autoscaling is available
34-
INFO[0179] ✅ CloudFormation is available
35-
INFO[0179] ✅ CloudWatch is available
36-
INFO[0180] ✅ EC2 is available
37-
INFO[0181] ✅ EC2messages is available
38-
INFO[0182] ✅ ECR is available
39-
INFO[0183] ✅ ECR Api is available
40-
INFO[0184] ✅ EKS is available
41-
INFO[0185] ✅ Elastic LoadBalancing is available
42-
INFO[0185] ✅ KMS is available
43-
INFO[0186] ✅ Kinesis Firehose is available
44-
INFO[0187] ✅ SSM is available
45-
INFO[0188] ✅ SSMmessages is available
46-
INFO[0189] ✅ SecretsManager is available
47-
INFO[0190] ✅ Sts is available
48-
INFO[0190] ✅ DynamoDB is available
49-
INFO[0191] ✅ S3 is available
50-
```
5+
## Prerequisites
6+
7+
1. Download the `gitpod-network-checker` binary using:
8+
```
9+
curl -L "https://github.com/gitpod-io/enterprise-deployment-toolkit/releases/download/v0.1.0/enterprise-deployment-toolkit_$(uname -s -m | awk '{print $1"_"$2}').tar.gz" | tar -xz
10+
```
11+
12+
You can also download and untar the binary directly from the Github releases page [here](https://github.com/gitpod-io/enterprise-deployment-toolkit/releases/latest)
13+
14+
Try running the command with help flag, to see if it downloaded properly:
15+
```
16+
./gitpod-network-checker --help
17+
```
18+
19+
2. Set up AWS credentials
20+
21+
`gitpod-network-checker` needs access to the AWS account you are planning to use to deploy Gitpod in. Much like AWS CLI, `gitpod-network-checker` uses the available AWS profile in your terminal to authenticate against the account. This means that you can rely on any locally available [AWS profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) or just set the right environment variables in your terminal for the CLI to use:
22+
```
23+
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
24+
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
25+
export AWS_SESSION_TOKEN=AQoDYXdzEJr...<remainder of security token>
26+
export AWS_REGION=eu-central-1 # Replace with the region you want to use
27+
```
28+
29+
## Usage
30+
31+
1. Preparation
32+
33+
To run a diagnosis of the network that you want to use for Gitpod, the CLI command needs to know the subnets you have chosen to be used as the `Main` subnets and the `Pod` subnets. You can read more about the distinction here in [our docs](https://www.gitpod.io/docs/enterprise/getting-started/networking#2-subnet-separation). The CLI expects to read the IDs of these subnets in a configuration file. By default it tries to read it from a file name `gitpod-network-check.yaml` in your current directory, but you can override this behavior by using the `--config` flag of the CLI.
34+
35+
For the sake of simplicity, let us create a file `gitpod-network-check.yaml` in the current directory and populate it with the subnet IDs and AWS region as shown below:
36+
```yaml
37+
log-level: debug # Options: debug, info, warning, error
38+
region: eu-central-1
39+
main-subnets: subnet-0554e84f033a64c56, subnet-08584621e7754e505, subnet-094c6fd68aea493b7
40+
pod-subnets: subnet-028d11dce93b8eefc, subnet-04ec8257d95c434b7,subnet-00a83550ce709f39c
41+
```
42+
43+
2. Run the network diagnosis
44+
45+
To start the diagnosis, the the command: `./gitpod-network-checker diagnose`
46+
47+
```
48+
./gitpod-network-checker diagnose
49+
INFO[0000] ✅ Main Subnets are valid
50+
INFO[0000] ✅ Pod Subnets are valid
51+
INFO[0000] ℹ️ Checking prerequisites
52+
INFO[0000] ✅ VPC endpoint com.amazonaws.eu-central-1.ec2messages is configured
53+
INFO[0000] ✅ VPC endpoint com.amazonaws.eu-central-1.ssm is configured
54+
INFO[0000] ✅ VPC endpoint com.amazonaws.eu-central-1.ssmmessages is configured
55+
INFO[0001] ℹ️ Launching EC2 instance in a Main subnet
56+
INFO[0007] ℹ️ Launching EC2 instance in a Pod subnet
57+
INFO[0009] ℹ️ Waiting for EC2 instances to become ready (can take up to 2 minutes)
58+
INFO[0167] ✅ EC2 Instances are now running successfully
59+
INFO[0167] ℹ️ Connecting to SSM...
60+
INFO[0175] ℹ️ Checking if the required AWS Services can be reached from the ec2 instances
61+
INFO[0178] ✅ Autoscaling is available
62+
INFO[0179] ✅ CloudFormation is available
63+
INFO[0179] ✅ CloudWatch is available
64+
INFO[0180] ✅ EC2 is available
65+
INFO[0181] ✅ EC2messages is available
66+
INFO[0182] ✅ ECR is available
67+
INFO[0183] ✅ ECR Api is available
68+
INFO[0184] ✅ EKS is available
69+
INFO[0185] ✅ Elastic LoadBalancing is available
70+
INFO[0185] ✅ KMS is available
71+
INFO[0186] ✅ Kinesis Firehose is available
72+
INFO[0187] ✅ SSM is available
73+
INFO[0188] ✅ SSMmessages is available
74+
INFO[0189] ✅ SecretsManager is available
75+
INFO[0190] ✅ Sts is available
76+
INFO[0190] ✅ DynamoDB is available
77+
INFO[0191] ✅ S3 is available
78+
```
79+

‎gitpod-network-check/cmd/root.go

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,8 +86,6 @@ func init() {
8686
networkCheckCmd.PersistentFlags().StringVar(&networkConfig.AwsRegion, "region", "eu-central-1", "AWS Region to create the cell in")
8787
networkCheckCmd.PersistentFlags().StringSliceVar(&networkConfig.MainSubnets, "main-subnets", []string{}, "List of main subnets")
8888
networkCheckCmd.PersistentFlags().StringSliceVar(&networkConfig.PodSubnets, "pod-subnets", []string{}, "List of pod subnets")
89-
networkCheckCmd.PersistentFlags().BoolVarP(&networkConfig.Destroy, "rm", "r", false, "Setting this will cleanup the stack at the end of diagnosis")
90-
networkCheckCmd.PersistentFlags().BoolVarP(&networkConfig.Cleanup, "cleanup", "c", false, "Cleanup an existing stack")
9189
bindFlags(networkCheckCmd, v)
9290
}
9391

0 commit comments

Comments
 (0)