Plural
Search…
Introduction
Workspace
Identity and Access Management
Debugging
API
Getting Started
Setting up your first cluster
1. Install Plural cli and dependencies
The Plural cli and dependencies are available using a package manager for your system. For Mac, we recommend using Homebrew, although our Docker image should be usable on virtually any platform
Mac
curl
Docker
EC2 AMI
1
brew install pluralsh/plural/plural
Copied!
The brew tap will install plural, alongside terraform, helm and kubectl for you. If you've already installed any of those dependencies, you can add
--without-helm, --without-terraform, or --without-kubectlYou can download the binaries attached to our github releases here: https://github.com/pluralsh/plural-cli/releases. There will be binaries for linux, windows, and mac and all compatible platforms.
​
For example, you can download v0.2.57 for Darwin arm64 via:
1
curl -L -o plural.tgz 'https://github.com/pluralsh/plural-cli/releases/download/v0.2.57/plural-cli_0.2.57_Darwin_arm64.tar.gz'
2
tar -xvf plural.tgz
3
chmod +x plural
4
mv plural /usr/local/bin/plural
Copied!
​
You will still need to ensure helm, terraform and kubectl are properly installed, you can find installers for each here
Tool
Installer
helm
terraform
kubectl
Once these are installed, you'll also need to add the helm push plugin like so
1
helm plugin install https://github.com/pluralsh/helm-push
Copied!
We offer a docker image with the plural cli installed along with all cli dependencies: terraform, helm, kubectl, and all the major cloud clis: gcr.io/pluralsh/plural-cli:0.1.1-cloud. We also provide a decent configuration of zsh in it, so you can drive the entire plural workflow in an interactive session. The best strategy is probably to mount the config dir of the cloud provider you're using, like (~/.aws), in the docker run command:
1
docker run -it --volume $HOME/.aws:/home/plural/aws \
2
--volume $HOME/.plural:/home/plural/.plural \
3
--volume $HOME/.ssh:/home/plural/.ssh \
4
--volume $HOME/<path-to-installation-repo:/home/plural/workspace \ # optional if you want to manage git via a volume
5
gcr.io/pluralsh/plural-cli:0.1.1-cloud zsh
Copied!
Once you're in the container's zsh, you'll want to clone the repo you'll use for your installations state there, or alternatively you can clone it outside your container and mount another volume pointing to it.
We have EC2 AMI's with plural cli installed, along with all cloud provider clis, terraform, helm and kubectl for those interested in creating a remote environment. A registry of the AMIs can be viewed here: https://github.com/pluralsh/plural-cli/blob/master/packer/manifest.json
If there's interest in images for GCP and Azure, please to give us a shout in our discord or feel free to open a github issue.
This doc gives more details on launching AMIs if you are unfamiliar: https://aws.amazon.com/premiumsupport/knowledge-center/launch-instance-custom-ami/. You'll want to select "Public images" within the ami search bar and you can use the ami id embedded in the
artifact_id in our manifests, eg ami-0249247d5fc865089. Be sure to chose the one for the appropriate region. ​
2. Install and Configure Cloud Provider CLI
GCP
AWS
Azure
- Verify that the cli has been added to your
$PATH - Create a new project in gcp via the cli:
1
gcloud projects create example-project-name
Copied!
- Run
gcloud initand follow the prompts to configure the gcloud cli and connect it to the project you just created. - Verify that your cli has been properly configured. It should look something like this. Make sure that your active configuration is set to the project you just created.
1
> gcloud config list
2
[compute]
3
region = us-east1
4
zone = us-east1-b
5
[core]
6
account = [email protected]
7
disable_usage_reporting = True
8
project = example-project-name
9
​
10
Your active configuration is: [example-project-name]
11
​
Copied!
- If you have multiple projects in GCP and previously have configured your gcloud cli to point to a different project, run
1
gcloud auth application-default login
Copied!
to reset the application default credential and re-authorize the browser. Failure to do this could result in
project requested not found errors further along.- Verify that the cli has been added to your
$PATH - Verify that your cli has been properly configured by running
1
aws configure list
Copied!
- You should see a set of values that looks like this:
1
Name Value Type Location
2
---- ----- ---- --------
3
profile <not set> None None
4
access_key ****************RUG2 shared-credentials-file
5
secret_key ****************hJUU shared-credentials-file
6
region us-east-2 config-file ~/.aws/config
Copied!
​
3. Register and Configure Domain Name
You need a registered domain that your Plural applications can be deployed to. You may use either:
- 1.
onplural.shsubdomain backed by the Plural Domain Service (recommended). If you are choosing to use the Plural domain service, you don't need to do anything extra now. Simply follow the prompts further down. - 2.your own domain or subdomain backed by one of the dns service providers we currently support:
- 1.Route53
- 2.Google Cloud DNS
- 3.Azure DNS
For more instructions on how to setup a domain using one of these providers refer to our guide here.
4. Create and Initialize Plural Repo
Currently we're limited to a one cluster to one repo mapping, but eventually that will be relaxed. We also strongly urge users to store installations in a fresh, separate repository to avoid our automation trampling existing files.
Clone your repo and then run from inside the repo:
1
plural init
Copied!
to log into plural, set the git attributes to configure encryption, and configure your cloud provider for this installation.
You will also be asked whether you want to use Plural's domain service and if so, what you want the subdomain to be. Here's an example of what it looks like below:
1
Do you want to use plural's dns provider: [Yn] Y
2
What do you want to use as your subdomain, must be a subdomain under onplural.sh: tryunitofwork.onplural.sh
Copied!
This process will generate a
workspace.yaml file at the root of your repo that stores your cloud provider configuration information.​
​
5. Install Plural Applications
To view the applications you can install on Plural, navigate to the explore tab at https://app.plural.sh/explore/public.
To actually install applications on Plural, the preferred method is to use our installation bundles. You can view the available bundles by navigating to the specific app on https://app.plural.sh or listing them via the cli using:
1
plural bundle list <app-name>
Copied!
If the app is paid, you should click on the bundle in the interface to ensure you set up all the subscriptions needed to install the application properly.
Once you've found the bundle you want and are ready to go, run this in the root of your repo:
1
plural bundle install <app-name> <bundle-name>
Copied!
You should be asked a lot of questions about how your app will be configured, including whether you want to enable Plural OIDC (single sign-on):
Unless you don't wish to use Plural as an identity provider due to internal company security requirements, you should enter (Y). This will enable you to use your existing
app.plural.sh login information to log into all Plural-deployed applications.Ultimately all the values you input at this step will be stored in a file called
context.yaml at the root of your repo. 6. Build and Deploy Plural Applications
With all bundles installed, simply run:
1
plural build
2
plural deploy --commit "initial deploy"
Copied!
This will generate all deployment artifacts in the repo, then deploy them in dependency order.
plural deploy can take a fair amount of time, and network disconnects can cause potential issues as a result. If you're running on a spotty network, or would like to step out while it's running we recommend running it in tmux​7. Install Plural Admin Console
The plural admin console is a web application that serves as a control panel for all your plural applications. It:
- manages automated upgrades delivered from the Kubernetes api
- serves as a thin Grafana to visualize application metrics and logs
- serves as a built-in k8s dashboard for all plural apps in the cluster, along with providing app-level health checking
- is the touchpoint at which incidents can be filed with the owner of an application
The console is not a strict dependency, but it is highly recommended to install it. It can be installed and deployed like any other application on Plural. For more detailed instructions, please refer to this guide.
8. Log In to Plural Application
Once
plural deploy has completed, you should be ready to log in to your application at {app-name}.{domain-name}. The application urls will have been printed out to the terminal at the end of the
plural deploy logs.If you selected (Y) to using Plural's OIDC above, then you should be able to login with your
app.plural.sh login credentials.If you selected (N) to using Plural's OIDC, login credentials are available at
{app-name}/helm/{app-name}/values.yaml. The key name should be pretty self-descriptive, for instance the initial admin password for the plural console is in a key named: console.secrets.admin_password.9. Upgrade and deploy new apps
The full
plural build && plural deploy commands are only necessary if you have a queue of multiple apps to be deployed that you need assistance with sequencing the installations. If there's just a single targeted application to deploy, simply do:1
plural build --only ${app}
2
plural deploy --commit "updated ${app}"
Copied!
10. Uninstall Applications
To uninstall applications, you can use
1
plural destroy <app-name>
Copied!
This will do things like destroying terraform resources and emptying k8s namespaces, but it won't remove the application builds from your local repo, or the application configuration values from
context.yaml. ​
11. Working in Teams
The getting started instructions here refer to a single user managing Plural installations for multiple applications. If you want to turn over management of your Plural-installed applications to a whole team, follow the instructions in the guide here.
​
Last modified 18d ago
Copy link
Edit on GitHub
Contents
1. Install Plural cli and dependencies
2. Install and Configure Cloud Provider CLI
3. Register and Configure Domain Name
4. Create and Initialize Plural Repo
5. Install Plural Applications
6. Build and Deploy Plural Applications
7. Install Plural Admin Console
8. Log In to Plural Application
9. Upgrade and deploy new apps
10. Uninstall Applications
11. Working in Teams