Skip to content

PiB Documentation - Top-Level README #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mindlessroman wants to merge 1 commit into
base: main
Choose a base branch
from
Open

PiB Documentation - Top-Level README #25

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
218 changes: 126 additions & 92 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,27 +2,45 @@

## Breaking Changes in 0.11.0

- Version 0.11.0 has breaking changes from 0.10.0
- The CLIs will automatically use the latest when you create a new Codespace
- Using the 0.11.0 or higher CLIs on an 0.10.0 branch will break
- To check the version of your CLI
- `kic -v`
- `flt -v`
- If you have an existing branch with work you want to save and create a new Codespace you can downgrade the CLI in that CS
- Make sure you're in the root of your branch repo
- `.devcontainer/cli-update.sh 0.10.0`
- To go back to the current CLI
- `.devcontainer/cli-update.sh`
>> **Warning!** Version `0.11.0` has breaking changes from `0.10.0`

The CLIs will automatically use the latest when you create a new Codespace, so using the `0.11.0` or
higher CLIs on an 0.10.0 branch will break. To check the version of your CLI use the `-v` flag:

- `kic -v`
- `flt -v`

If you have an existing branch with work you want to save and create a new Codespace you can downgrade
the CLI in that codespace.

> **NOTE**: Make sure you're in the root of your branch repo when you run the following.

```bash
.devcontainer/cli-update.sh 0.10.0`
```

To go back to the current CLI: `.devcontainer/cli-update.sh`.

## Introduction

Kubernetes is hard. Getting started and set up for the first time can take weeks to get right. Managing deployments on a fleet of Kubernetes clusters on the edge brings even more challenges.
Kubernetes is hard. Getting started and set up for the first time can take weeks to get right.
Managing deployments on a fleet of Kubernetes clusters on the edge brings even more challenges.

Pilot-in-a-Box (PiB) is a `game-changer` for the end-to-end Kubernetes app development cycle from a local cluster to deployments on the edge. It reduces the initial friction and empowers the developer to get started and deployed to a dev/test environment within *minutes*. The pre-configured Codespaces environment includes a `Kubernetes` cluster and custom CLI's (`kic` and `flt`) that help streamline the initial learning curve to Kubernetes development commands.
Pilot-in-a-Box (PiB) is a `game-changer` for the end-to-end Kubernetes app development cycle from a
local cluster to deployments on the edge. It reduces the initial friction and empowers the developer
to get started and deployed to a dev/test environment within *minutes*. The pre-configured Codespaces
environment includes a `Kubernetes` cluster and custom CLI's (`kic` and `flt`) that help streamline
the initial learning curve to Kubernetes development commands.

This repo walks through the rich end-to-end developer experience in a series of labs. The labs start by walking you through creating, building, testing, and deploying an application on a local cluster ([inner-loop](./README.md#inner-loop)) with a complete CNCF observability stack. Then, the labs move on to the next step of deploying the application to a test cluster in the Cloud ([outer-loop](./README.md#outer-loop)). There are also several [advanced labs](./README.md#advanced-labs) that cover centralized monitoring, canary deployments, and targeting different devices.
This repo walks through the rich end-to-end developer experience in a series of labs. The labs start
by walking you through creating, building, testing, and deploying an application on a local cluster
([inner-loop](./README.md#inner-loop)) with a complete CNCF observability stack. Then, the labs move
on to the next step of deploying the application to a test cluster in the Cloud ([outer-loop](./README.md#outer-loop)).
There are also several [advanced labs](./README.md#advanced-labs) that cover centralized monitoring,
canary deployments, and targeting different devices.

> Note: PiB is not intended as-is for production deployments. However, some concepts covered (GitOps and Observability) are production-ready.
> **NOTE**: PiB is not intended as-is for production deployments. However, some concepts covered (GitOps
> and Observability) are production-ready.

## Prerequisites

Expand All @@ -33,128 +51,144 @@ This repo walks through the rich end-to-end developer experience in a series of

## GitHub Codespaces

> Codespaces allows you to develop in a secure, configurable, and dedicated development environment in the cloud that works how and where you want it to
> Codespaces allows you to develop in a secure, configurable, and dedicated development environment
> in the cloud that works how and where you want it to.

Check out the [GitHub Codespaces Overview](https://docs.github.com/en/codespaces). GitHub Codespaces
is available for organizations using GitHub Team or GitHub Enterprise Cloud. Codespaces are also available
as a limited beta release for individual users on GitHub Pro plans. However, the waiting list
is normally > 3 months.

- [GitHub Codespaces Overview](https://docs.github.com/en/codespaces)
- GitHub Codespaces is available for organizations using GitHub Team or GitHub Enterprise Cloud. GitHub Codespaces is also available as a limited beta release for individual users on GitHub Pro plans.
- For more information, see ["GitHub's products"](https://docs.github.com/en/get-started/learning-about-github/githubs-products)
For more information, see ["GitHub's products"](https://docs.github.com/en/get-started/learning-about-github/githubs-products).

We use GitHub Codespaces for our `inner-loop` and `outer-loop` Developer Experiences. While other DevX are available, currently, we only support GitHub Codespaces.
We use GitHub Codespaces for our `inner-loop` and `outer-loop` Developer Experiences. While other DevX
are available, currently, we only support GitHub Codespaces.

The easiest way to get GitHub Codespaces access is to setup a [GitHub Team](https://docs.github.com/en/codespaces)
The easiest way to get GitHub Codespaces access is to setup a [GitHub Team](https://docs.github.com/en/codespaces).

GitHub Codespaces is also available in beta on a limited basis for GitHub Pro users. The waiting list is normally > 3 months.
> Best Practice: as you begin projects, ensure that you have Codespaces and Azure subscriptions with
> proper permissions.

> Best Practice: as you begin projects, ensure that you have Codespaces and Azure subscriptions with proper permissions
## `inner-loop`

## inner-loop
The `inner-loop` refers to the tasks that developers do every day as part of their development process.
Generally, `inner-loop` happens on the individual developer workstation. For PiB, the inner-loop and
developer workstation is Codespaces. When a developer creates a Codespace, that is their "personal
development workstation in the cloud." As part of PiB, we have automated the creation of the developer
workstation using a repeatable, consistent, Infrastructure as Code (IaC) approach.

- `inner-loop` refers to the tasks that developers do every day as part of their development process
- Generally, `inner-loop` happens on the individual developer workstation
- For PiB, the inner-loop and developer workstation is Codespaces
- When a developer creates a Codespace, that is their "personal development workstation in the cloud"
- As part of PiB, we have automated the creation of the developer workstation using a repeatable, consistent, Infrastructure as Code approach
- We have an advanced workshop planned for customizing the Codespaces experience for your project
- With the power of Codespaces, a developer can create a consistent workstation with a few clicks in less than a minute
We have an advanced workshop planned for customizing the Codespaces experience for your project. With
the power of Codespaces, a developer can create a consistent workstation with a few clicks in less than
a minute.

## outer-loop
## `outer-loop`

- `outer-loop` refers to the tasks that developers and DevOps do as they move from dev to test to pre-prod to production
- Generally `outer-loop` happens on shared compute outside of the developer workstation
- For PiB, outer-loop uses a combination of Codespaces and `dev/test clusters` in Azure
- As part of PiB, we have automated the creation of dev/test clusters using a repeatable, consistent, Infrastructure as Code approach
The `outer-loop` refers to the tasks that developers and DevOps do as they move from dev to test to
pre-prod to production stages. Generally `outer-loop` happens on shared compute outside of the
developer workstation. For PiB, `outer-loop` uses a combination of Codespaces and `dev/test clusters`
in Azure. As part of PiB, we have automated the creation of dev/test clusters using a repeatable,
consistent, IaC approach.

## Create a Codespace

> You can use the same Codespace for any of the labs
> **NOTE**: You can use the same Codespace for any of the labs.

- From this repo
- Click the `<> Code` button
- Make sure the Codespaces tab is active
- Click `Create Codespace on main`
- After about 1 minute, you will have a GitHub Codespace running with a complete Kubernetes Developer Experience!
From this repo, click the `<> Code` button. Make sure the Codespaces tab is active. Choose
`Create Codespace on main`. After about 1 minute, you will have a GitHub Codespace running with a
complete Kubernetes developer experience!

## Note on environment variables

- Many of these tutorials make use of environment variables, using the export functionality. If you wish, you can also edit the Z shell preferences file to persist exported environment variables across terminal sessions. Just add the same "export FOO=BAR" lines to your .zshrc file.
Many of these tutorials make use of environment variables, using the export functionality. If you
wish, you can also edit the Z shell preferences file to persist exported environment variables
across terminal sessions. Just add the same "export FOO=BAR" lines to your `.zshrc` file.

```bash

nano ~/.zshrc

```

## Create a working branch

- Because the main branch has a branch protection rule, you need to create a working branch
- You can use the same branch for any of the labs or create a new branch per lab (add 1, 2, 3 ... to the branch name)
Because the main branch has a branch protection rule, you need to create a working branch. You can
use the same branch for any of the labs or create a new branch per lab (add 1, 2, 3 ... to the branch
name).

> 🛑 Many commands will fail in following labs if `MY_BRANCH` is not set or branch is not pushed upstream
> **NOTE**: 🛑 Many commands will fail in following labs if `MY_BRANCH` is not set or that branch is
> not pushed upstream.

```bash

# by default, MY_BRANCH is set to your lower case GitHub User Name
# the value can be overwritten if needed
echo $MY_BRANCH

# create a branch
git checkout -b $MY_BRANCH
```bash
# by default, MY_BRANCH is set to your lower case GitHub User Name
# the value can be overwritten if needed
echo $MY_BRANCH

# push the branch and set the remote
git push -u origin $MY_BRANCH
# create a branch
git checkout -b $MY_BRANCH

```
# push the branch and set the remote
git push -u origin $MY_BRANCH
```

- Your prompt should end like this
- /workspaces/Pilot-in-a-Box (mybranch) $
Your prompt should end like this `/workspaces/Pilot-in-a-Box (mybranch) $ ...`.

## inner-loop Labs

- [Lab 1](./labs/inner-loop.md#pib-inner-loop): Create, build, deploy, and test a new dotnet application and observability stack on your local cluster
- [Lab 2](./labs/inner-loop-flux.md#create-a-new-cluster): Configure flux to automate the deployment process from Lab 1
- [Lab 1](./labs/inner-loop.md#pib-inner-loop): Create, build, deploy, and test a new dotnet application
and observability stack on your local cluster.
- [Lab 2](./labs/inner-loop-flux.md#create-a-new-cluster): Configure flux to automate the deployment
process from Lab 1.

## outer-loop Labs

- [Lab 1](./labs/outer-loop.md#pib-outer-loop): Create a dev/test cluster and manage application deployments on the cluster
- [Lab 2](./labs/outer-loop-multi-cluster.md#pib-outer-loop-multi-cluster): Manage application deployments on a fleet of multiple clusters
- [Lab 3](./labs/outer-loop-ring-deployment.md#pib-outer-loop-with-ring-based-deployment): Configure ring based deployments

- [Lab 4](./labs/azure-codespaces-setup.md#azure-subscription-and-codespaces-setup): Set up Azure subscription and Codespaces for advanced configuration
- [Lab 1](./labs/outer-loop.md#pib-outer-loop): Create a dev/test cluster and manage application
deployments on the cluster.
- [Lab 2](./labs/outer-loop-multi-cluster.md#pib-outer-loop-multi-cluster): Manage application deployments
on a fleet of multiple clusters.
- [Lab 3](./labs/outer-loop-ring-deployment.md#pib-outer-loop-with-ring-based-deployment): Configure
ring-based deployments.
- [Lab 4](./labs/azure-codespaces-setup.md#azure-subscription-and-codespaces-setup): Set up Azure
subscription and Codespaces for advanced configuration.
- This is a prerequisite for the Advanced Labs

## Advanced Labs

- [Arc enabled GitOps Lab](./labs/outer-loop-arc-gitops.md#pib-outer-loop-with-arc-enabled-gitops): Deploy to dev cluster running on an Azure VM with Arc enabled GitOps
- [Canary Deployment Lab](./labs/advanced-labs/canary/README.md#pib-automated-canary-deployment-using-flagger): Use Flagger to experiment with canary deployments
- [Vision on Edge (VoE) Lab](./labs/advanced-labs/voe/README.md#pib-outer-loop-vision-on-edge-voe): Deploy a more complex app (VoE) to a fleet
- [Centralized Observability Lab](./labs/advanced-labs/monitoring/README.md#pib-centralized-monitoring): Deploy a centralized observability system with Fluent Bit, Prometheus, and Grafana to monitor fleet application deployments
- [outer-loop with AKS-IoT](./labs/advanced-labs/aks-iot/README.md#pib-outer-loop-to-aks-iot): Deploy to an AKS-IoT cluster running on an Azure VM with Arc enabled GitOps
- [outer-loop with AKS Lab](./labs/outer-loop-aks-azure.md#pib-outer-loop-to-aks-on-azure): Deploy to an AKS cluster with Arc enabled GitOps
- [Arc enabled GitOps Lab](./labs/outer-loop-arc-gitops.md#pib-outer-loop-with-arc-enabled-gitops):
Deploy to dev cluster running on an Azure VM with Arc enabled GitOps.
- [Canary Deployment Lab](./labs/advanced-labs/canary/README.md#pib-automated-canary-deployment-using-flagger):
Use Flagger to experiment with canary deployments.
- [Vision on Edge (VoE) Lab](./labs/advanced-labs/voe/README.md#pib-outer-loop-vision-on-edge-voe):
Deploy a more complex app (VoE) to a fleet.
- [Centralized Observability Lab](./labs/advanced-labs/monitoring/README.md#pib-centralized-monitoring):
Deploy a centralized observability system with Fluent Bit, Prometheus, and Grafana to monitor fleet
application deployments.
- [outer-loop with AKS-IoT](./labs/advanced-labs/aks-iot/README.md#pib-outer-loop-to-aks-iot): Deploy
to an AKS-IoT cluster running on an Azure VM with Arc enabled GitOps.
- [outer-loop with AKS Lab](./labs/outer-loop-aks-azure.md#pib-outer-loop-to-aks-on-azure): Deploy to
an AKS cluster with Arc enabled GitOps.

## Cleanup

- Once you are finished with all of the labs and experimenting, please delete your branch

```bash
- Once you are finished with all of the labs and experimenting, please delete your branch.

# change to the root of the repo
cd $PIB_BASE

git pull
git add .
git commit -am "deleting branch"
git push

# checkout main branch, delete remote, delete local
git checkout main
git push origin $MY_BRANCH --delete
git branch -D $MY_BRANCH

```
```bash
# change to the root of the repo
cd $PIB_BASE

git pull
git add .
git commit -am "deleting branch"
git push

# checkout main branch, delete remote, delete local
git checkout main
git push origin $MY_BRANCH --delete
git branch -D $MY_BRANCH
```

## Support

This project uses GitHub Issues to track bugs and feature requests. Please search the existing issues before filing new issues to avoid duplicates. For new issues, file your bug or feature request as a new issue.
This project uses GitHub Issues to track bugs and feature requests. Please search the existing issues
before filing new issues to avoid duplicates. For new issues, file your bug or feature request as a
new issue. See the [Contributing Guidance](.github/CONTRIBUTING.md) for more details.

## Contributing

Expand Down