UNCLASSIFIED - NO CUI

Skip to content
Snippets Groups Projects
Commit b885f325 authored by Michael Martin's avatar Michael Martin
Browse files

Merge branch 'quickstart_k3d_docs' into 'master' 

Update quickstart documentation, make k3d-dev reprint instructions

See merge request !5785
parents 89f0bd93 50ee74c8
No related branches found
No related tags found
1 merge request!5785Update quickstart documentation, make k3d-dev reprint instructions
Pipeline #3958321 passed with warnings
Stage: 🎛 prevar
Stage: 🔥 smoke tests
Hide whitespace changes
Inline Side-by-side
docs/assets/scripts/developer/k3d-dev.sh
+ 56
− 39
View file @ b885f325
......@@ -6,6 +6,7 @@
K3D_VERSION="5.7.3"
DEFAULT_K3S_TAG="v1.31.4-k3s1"
PROVISION_CLOUD_INSTANCE=true
CLOUDPROVIDER="aws"
SSHUSER=ubuntu
action=create_instances
......@@ -60,18 +61,15 @@ function process_arguments {
case "$1" in
-t|--project-tag)
echo "-t|--project-tag option passed to use additional tags on instance"
shift
PROJECTTAG=$1
;;
-b|--big-instance)
echo "-b|--big-instance option passed for big k3d cluster using M5 instance"
BIG_INSTANCE=true
;;
-p|--use-private-ip)
echo "-p|--use-private-ip option passed to create k3d cluster with private ip"
if [[ "${ATTACH_SECONDARY_IP}" = false ]]; then
PRIVATE_IP=true
else
......@@ -80,64 +78,55 @@ function process_arguments {
;;
-m|--use-metallb)
echo "-m option is deprecated (default behavior is to install and use metallb)"
;;
-M|--disable-metallb)
echo "Disabling metalLB"
METAL_LB=false
;;
-a|--attach-secondary-public-ip)
echo "-a option passed to create secondary public IP (-p and -m flags are skipped if set)"
PRIVATE_IP=false
METAL_LB=false
ATTACH_SECONDARY_IP=true
;;
-d|--destroy-cloud-instance)
echo "-d option passed to destroy the AWS resources"
action=destroy_instances
;;
-i|--init-script)
echo "-i option passed to send init script to k3d instance"
shift
INIT_SCRIPT=$1
;;
-H|--existing-public-ip)
echo "-H option passed to use existing system public IP"
shift
PublicIP=$1
PROVISION_CLOUD_INSTANCE=false
CLOUDPROVIDER=""
;;
-P|--existing-private-ip)
echo "-P option passed to use existing system private IP"
shift
PrivateIP=$1
;;
-U|--ssh-username)
echo "-U option passed to provide username for connecting to existing system"
shift
SSHUSER=$1
;;
-k|--ssh-keyfile)
echo "-k option passed to provide SSH key for connecting to existing system"
shift
SSHKEY=$1
;;
-c|--cloud-provider)
echo "-c option passed to specify cloud provider"
shift
CLOUDPROVIDER=$1
;;
-T|--no-terminate)
echo "-T option passed to prevent instance termination"
TERMINATE_INSTANCE=false
;;
-q|--quiet)
......@@ -187,6 +176,8 @@ function process_arguments {
echo " -T|--no-terminate Don't terminate the instance after"
echo " 8 hours"
echo " -q|--quiet suppress the final completion message"
echo " -I|--print-instructions Print the instructional message for the"
echo " instance described or discovered and exit"
echo
echo "========= These options override -c and use your own infrastructure ======="
echo
......@@ -202,11 +193,14 @@ function process_arguments {
echo " -h|--help output this help"
exit 0
;;
-I|--print-instructions)
action=print_instructions
;;
-K|--recreate-k3d)
RESET_K3D=true
;;
-R|--recreate-cloud-instance)
CLOUD_RECREATE_INSTANCE=true
export CLOUD_RECREATE_INSTANCE=true
;;
-u|--update-cloud-instance)
action=update_instances
......@@ -217,7 +211,6 @@ function process_arguments {
;;
-w|--use-weave-cni)
echo "-w option passed to use Weave CNI"
USE_WEAVE=true
;;
......@@ -284,8 +277,6 @@ function cloud_aws_configure {
echo "You must configure your AWS credentials. Your AWS user name is used to name resources in AWS. Example:"
echo " aws configure"
exit 1
else
echo "AWS User Name: ${AWSUSERNAME}"
fi
if [[ -z "${VPC_ID}" ]]; then
......@@ -343,7 +334,7 @@ function cloud_aws_report_instances {
}
function set_kubeconfig {
if [[ "$PublicIP" != "" ]]; then
if [[ "${PROVISION_CLOUD_INSTANCE}" == "false" ]]; then
KUBECONFIG=${PublicIP}-dev-${PROJECTTAG}-config
elif [[ "${AWSUSERNAME}" != "" ]]; then
KUBECONFIG=${AWSUSERNAME}-dev-${PROJECTTAG}-config
......@@ -475,8 +466,9 @@ function update_ec2_security_group {
}
function destroy_instances {
if [[ "$PublicIP" != "" ]] && [[ "${CLOUD_RECREATE_INSTANCE}" != "true" ]]; then
echo "Public IP of instance has been provided; assuming instance was not provisioned by me."
if [[ "${PROVISION_CLOUD_INSTANCE}" == "false" ]] && [[ "${CLOUD_RECREATE_INSTANCE}" != "true" ]]; then
echo "The current instance may not have been provisioned by k3d-dev. It is probably not appropriate"
echo "for k3d-dev to attempt to destroy it."
echo "Nothing to do."
exit 1
fi
......@@ -782,12 +774,13 @@ EOF
}
function print_instructions {
echo
echo "================================================================================"
echo "====================== DEPLOYMENT FINISHED ====================================="
echo "================================================================================"
check_for_existing_instances
if [[ $? -eq 0 ]]; then
echo "There does not appear to be a valid existing instance matching the arguments provided." >&2
echo "Cannot generate instructions." >&2
exit 1
fi
# ending instructions
echo
echo "SAVE THE FOLLOWING INSTRUCTIONS INTO A TEMPORARY TEXT DOCUMENT SO THAT YOU DON'T LOSE THEM"
if [[ "$TERMINATE_INSTANCE" != "false" ]]; then
echo "NOTE: The EC2 instance will automatically terminate 8 hours from the time of creation unless you delete the root cron job"
......@@ -1111,7 +1104,6 @@ function cluster_mgmt_select_action_for_existing {
exit 1
fi
RESET_K3D=true
SecondaryIP=$(aws ec2 describe-instances --output json --no-cli-pager --instance-ids ${InstId} | jq -r '.Reservations[0].Instances[0].NetworkInterfaces[0].PrivateIpAddresses[] | select(.Primary==false) | .Association.PublicIp')
PrivateIP2=$(getPrivateIP2)
if [[ "${ATTACH_SECONDARY_IP}" == true && -z "${SecondaryIP}" ]]; then
echo "Secondary IP didn't exist at the time of creation of the instance, so cannot attach one without re-creating it with the -a flag selected."
......@@ -1135,15 +1127,26 @@ function cluster_mgmt_select_action_for_existing {
done
}
function cloud_aws_check_for_existing_instances {
if [[ "${InstId}" == "" ]]; then
export InstId=$(aws ec2 describe-instances \
--output text \
--query "Reservations[].Instances[].InstanceId" \
--filters "Name=tag:Name,Values=${AWSUSERNAME}-dev" "Name=tag:Project,Values=${PROJECTTAG}" "Name=instance-state-name,Values=running")
if [[ $InstId ]]; then
export PublicIP=$(aws ec2 describe-instances --output text --no-cli-pager --instance-id ${InstId} --query "Reservations[].Instances[].PublicIpAddress")
export PrivateIP=$(aws ec2 describe-instances --output json --no-cli-pager --instance-ids ${InstId} | jq -r '.Reservations[0].Instances[0].PrivateIpAddress')
export SecondaryIP=$(aws ec2 describe-instances --output json --no-cli-pager --instance-ids ${InstId} | jq -r '.Reservations[0].Instances[0].NetworkInterfaces[0].PrivateIpAddresses[] | select(.Primary==false) | .Association.PublicIp')
return 1
fi
return 0
fi
return 1
}
function cloud_aws_create_instances {
echo "Checking for existing cluster for ${AWSUSERNAME}."
InstId=$(aws ec2 describe-instances \
--output text \
--query "Reservations[].Instances[].InstanceId" \
--filters "Name=tag:Name,Values=${AWSUSERNAME}-dev" "Name=tag:Project,Values=${PROJECTTAG}" "Name=instance-state-name,Values=running")
if [[ $InstId ]]; then
PublicIP=$(aws ec2 describe-instances --output text --no-cli-pager --instance-id ${InstId} --query "Reservations[].Instances[].PublicIpAddress")
PrivateIP=$(aws ec2 describe-instances --output json --no-cli-pager --instance-ids ${InstId} | jq -r '.Reservations[0].Instances[0].PrivateIpAddress')
cloud_aws_check_for_existing_instances
if [[ $? -ne 0 ]]; then
echo "Existing cluster found running on instance ${InstId} on ${PublicIP} / ${PrivateIP}"
if [[ "${RESET_K3D}" != "true" ]] && [[ "${CLOUD_RECREATE_INSTANCE}" != "true" ]]; then
cluster_mgmt_select_action_for_existing
......@@ -1218,8 +1221,18 @@ ENDSSH
fi
}
function check_for_existing_instances {
if [[ "${PROVISION_CLOUD_INSTANCE}" == "true" ]]; then
cloud_${CLOUDPROVIDER}_check_for_existing_instances
return $?
fi
# We are not provisioning a cloud instance. Assume that whatever arguments the user provided
# does represent a running instance.
return 1
}
function create_instances {
if [[ "${PublicIP}" == "" ]]; then
if [[ "${PROVISION_CLOUD_INSTANCE}" == "true" ]]; then
cloud_${CLOUDPROVIDER}_create_instances
fi
initialize_instance
......@@ -1228,6 +1241,11 @@ function create_instances {
install_metallb
fix_etc_hosts
if [[ "${QUIET}" == "false" ]]; then
echo
echo "================================================================================"
echo "====================== DEPLOYMENT FINISHED ====================================="
echo "================================================================================"
echo
print_instructions
fi
}
......@@ -1241,9 +1259,7 @@ function main {
fi
check_missing_tools ${extratools}
# When -H is NOT provided, we assume we're responsible
# for provisioning the cloud infra.
if [[ "$PublicIP" == "" ]]; then
if [[ "${PROVISION_CLOUD_INSTANCE}" == "true" ]]; then
cloud_${CLOUDPROVIDER}_configure
else
CLOUDPROVIDER=""
......@@ -1251,6 +1267,7 @@ function main {
set_kubeconfig
check_for_existing_instances
${action}
}
......
docs/assets/scripts/quickstart.sh
+ 1
− 10
View file @ b885f325
......@@ -352,17 +352,8 @@ function main {
echo "=================================================================================="
echo " INSTALLATION COMPLETE"
echo ""
echo "To access your kubernetes cluster via kubectl, export this variable in your shell:"
build_k3d_cluster --print-instructions
echo
echo " export KUBECONFIG=${KUBECONFIG}"
echo
echo "To access your kubernetes cluster in your browser, add this line to your hosts file:"
echo
echo " ${arg_host} ${services}"
echo
echo "To SSH to the instance running your cluster, use this command:"
echo
echo " ssh -i ${arg_keyfile} -o StrictHostKeyChecking=no -o IdentitiesOnly=yes ${arg_username}@${arg_host}"
echo "=================================================================================="
set +e
}
......
docs/guides/deployment-scenarios/quickstart.md
+ 49
− 25
View file @ b885f325
......@@ -12,6 +12,7 @@ An SRE with a reasonable amount of experience operating in a command line enviro
1. Install [jq](https://jqlang.github.io/jq/download/).
1. Install [yq](https://github.com/mikefarah/yq/#install). yq needs to be available in your system path PATH as `yq`, so we recommend not using a dockerized installation.
1. Install kubectl. Follow the instructions for [windows](https://kubernetes.io/docs/tasks/tools/install-kubectl-windows/), [macos](https://kubernetes.io/docs/tasks/tools/install-kubectl-macos/) or [linux](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/). (If you are running on WSL in Windows, you should install kubectl using the package manager inside of WSL to install kubectl.)
1. Install [sshuttle](https://sshuttle.readthedocs.io/en/stable/installation.html)
1. [Install helm](https://helm.sh/docs/intro/install/).
1. [Install the Flux CLI](https://fluxcd.io/flux/installation/).
1. Ensure you have bash version 4 installed. Linux and Windows with WSL users probably don't need to worry about this. For Mac OS users, install bash4 with homebrew or a similar package manager, as the bash that ships with Mac OS is hopelessly old. Mac OS users will use `/opt/homebrew/bin/bash` whenever `bash` is mentioned in this guide.
......@@ -64,20 +65,40 @@ Eventually the bigbang release process will finish, and you'll see output like t
```
==================================================================================
INSTALLATION COMPLETE
INSTALLATION COMPLETE
SAVE THE FOLLOWING INSTRUCTIONS INTO A TEMPORARY TEXT DOCUMENT SO THAT YOU DON'T LOSE THEM
ssh to instance:
ssh -i ${SSHKEY} -o IdentitiesOnly=yes ${SSHUSER}@${PublicIP}
To use kubectl from your local workstation you must set the KUBECONFIG environment variable:
export KUBECONFIG=~/.kube/${PublicIP}-dev-quickstart-config
OPTION 1: ACCESS APPLICATIONS WITH WEB BROWSER ONLY
To access apps from browser only start ssh with application-level port forwarding:
ssh -i ${SSHKEY} ${SSHUSER}@${PublicIP} -D 127.0.0.1:12345
Do not edit /etc/hosts on your local workstation.
Edit /etc/hosts on the EC2 instance. Sample /etc/host entries have already been added there.
Manually add more hostnames as needed.
The IPs to use come from the istio-system services of type LOADBALANCER EXTERNAL-IP that are created when Istio is
deployed.
You must use Firefox browser with with manual SOCKs v5 proxy configuration to localhost with port 12345.
Also ensure 'Proxy DNS when using SOCKS v5' is checked.
Or, with other browsers like Chrome you could use a browser plugin like foxyproxy to do the same thing as Firefox.
OPTION 2: ACCESS APPLICATIONS WITH WEB BROWSER AND COMMAND LINE
To access apps from browser and from the workstation command line start sshuttle in a separate terminal window.
sshuttle --dns -vr ${SSHUSER}@${PublicIP} 172.20.1.0/24 --ssh-cmd 'ssh -i ${SSHKEY}'
Edit your workstation /etc/hosts to add the LOADBALANCER EXTERNAL-IPs from the istio-system services with applicat
ion hostnames.
Here is an example. You might have to change this depending on the number of gateways you configure for k8s cluste
r.
# METALLB ISTIO INGRESS IPs
172.20.1.240 keycloak.dev.bigbang.mil vault.dev.bigbang.mil
172.20.1.241 sonarqube.dev.bigbang.mil prometheus.dev.bigbang.mil nexus.dev.bigbang.mil gitlab.dev.bigbang.mil
To access your kubernetes cluster via kubectl, export this variable in your shell:
export KUBECONFIG=~/.kube/192.168.1.123-quickstart-dev-config
To access your kubernetes cluster in your browser, add this line to your hosts file:
192.168.1.123 alertmanager.dev.bigbang.mil prometheus.dev.bigbang.mil grafana.dev.bigbang.mil
To SSH to the instance running your cluster, use this command:
ssh -i ~/.ssh/192.168.1.123-dev-quickstart.pem -o StrictHostKeyChecking=no -o IdentitiesOnly=yes ubuntu@192.168.1.123
================================================================================
==================================================================================
```
Congratulations, it's ready!
......@@ -100,30 +121,33 @@ The quickstart.sh script performs several actions:
### Fix DNS to access the services in your browser
You can now access your bigbang kubernetes cluster from the command line using `kubectl`, but you will need to perform one extra step to easily access bigbang services in your web browser. You will need to manually override some DNS settings to send specific website requests to your kubernetes cluster. This was included in the final message of the quickstart, but here are the instructions again.
You can now access your bigbang kubernetes cluster from the command line using `kubectl`, but you will need to perform one extra step to easily access bigbang services in your web browser (or from the command line using utilities like `curl`). You will need to manually override some DNS settings to send specific website requests to your kubernetes cluster. This was included in the final message of the quickstart, but here are the instructions again.
**Remember to un-do this step when you are done experimenting with the bigbang quickstart.**
#### Linux/Mac Users
You need to edit your system hosts file to add the LOADBALANCER EXTERNAL-IPs from the istio-system services with application hostnames. Your cluster is configured with two different gateways for different methods of TLS termination, and each gateway has its own IP.
Run this command in your terminal:
Open your system hosts file in your favorite editor. You will need to run the editor with administrator privileges in order to edit the hosts file. The file is in different locations for different operating systems:
```shell
echo YOUR_VM_IP $(kubectl get virtualservices -A -o json | jq -r .items[].spec.hosts[0] | tr "\n" "\t") | sudo tee -a /etc/hosts
* Linux/Mac : `/etc/hosts`
* Windows: `C:\Windows\System32\drivers\etc\hosts`
Add the following lines at the end of the file:
```
172.20.1.240 keycloak.dev.bigbang.mil vault.dev.bigbang.mil
172.20.1.241 sonarqube.dev.bigbang.mil prometheus.dev.bigbang.mil nexus.dev.bigbang.mil gitlab.dev.bigbang.mil
```
#### Windows Users
### Start a lightweight VPN into your k3d cluster
Run this command in your bash terminal, and copy the output to your clipboard.
Now, start the sshuttle command in a separate terminal window. This acts as a lightweight VPN that redirects traffic through the VM running your k3d cluster. Although the load balancer IP addresses are considered "external" from k3d's perspective, they are in fact not publicly accessible, but are internal and must be accessed through this lightweight VPN. Don't let the terminology confuse you. You will need to provide administrator privileges (sudo) on your workstation for this to function.
```shell
echo YOUR_VM_IP $(kubectl get virtualservices -A -o json | jq -r .items[].spec.hosts[0] | tr "\n" "\t")
sshuttle --dns -vr ${SSHUSER}@${PublicIP} 172.20.1.0/24 --ssh-cmd 'ssh -i ${SSHKEY}'
```
1. Right click Notepad -> Run as Administrator
1. Open C:\Windows\System32\drivers\etc\hosts
1. Add the line from your clipboard to the bottom of the file
1. Save and close
You will need to leave this command running for as long as you want to access your cluster.
### Access a BigBang Service
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

UNCLASSIFIED - NO CUI