Besom
Besom - a broom made of twigs tied around a stick. Brooms and besoms are used for protection, to ward off evil spirits, and cleansing of ritual spaces. Also, an experimental pulumi-scala implementation, incidentally.
Getting started
Publish necessary packages
Prerequisites: pulumi, just, scala-cli, java, go, protoc, git, unzip,
Publish locally and install necessary Besom packages:
just publish-local-core
just publish-local-compiler-plugin
just install-language-plugin
Publish additional SDKs
You have to generate an SDK for a provider of your choice, to do that run:
just generate-provider-sdk ${provider_name} ${provider_version}
just publish-local-provider-sdk ${provider_name} ${provider_version}
e.g.:
just generate-provider-sdk kubernetes 4.2.0
just publish-local-provider-sdk kubernetes 4.2.0
Initialize your code with a template
You can start writing your code at this point but to help you set up Besom comes with Pulumi templates. More information about templates in ./template/README
To initialize your project with chosen template run this in an empty folder:
pulumi new ${path_to_the_template}
e.g.:
cd ..
mkdir infra
cd infra
pulumi new ../besom/template/kubernetes
Explaining the file structure
Pulumi.yaml
is your main Pulumi file, explained here.
project.scala
is the file containing your dependencies.
Main.scala
is the entry point for your infrastructure as code.
Resources created in Pulumi.run{ ... }
block will be created by Pulumi.
Setting up the code editor
Both IDEs support rely on BSP.
BSP setup
Build experimental scala-compose
and place on $PATH
:
git clone [email protected]:VirtusLab/scala-compose.git
cd scala-compose
cat << EOF | git apply
> diff --git a/project/publish.sc b/project/publish.sc
> index e00f81ca..619d4c99 100644
> --- a/project/publish.sc
> +++ b/project/publish.sc
> @@ -113,8 +113,9 @@ def finalPublishVersion = {
> }
> else
> T {
> - val state = VcsVersion.vcsState()
> - computePublishVersion(state, simple = true)
> + // val state = VcsVersion.vcsState()
> + // computePublishVersion(state, simple = true)
> + "1.0.4"
> }
> }
>
> EOF
./mill -i show scala-compose.nativeImage
cp out/scala-compose/base-image/nativeImage.dest/scala-cli ~/bin/scala-compose
Use scala-compose
in besom
directory:
scala-compose setup-ide --conf-dir .
IntelliJ setup
IntelliJ support is experimental.
- Make sure you have the latest IntelliJ
- Install Scala plugin and set update chanel to "Nightly Builds"
- Use BSP (documentation)
Make sure you have .bsp
directory before you open the project in IntelliJ.
Additionally, please set scalafmt
as the formatter.
VSCode setup
If you are using VSCode:
- Install Metals
- Open the project in Metals.
Make sure you have .bsp
directory before you open the project in IntelliJ.
This might not be enough if your infrastructure is just a part (a module) of your existing Scala project. For this to work you have to make your build tool aware of the infrastructure code, for sbt create a corresponding module:
lazy val infra = project.in(file("infrastructure")).settings(
libraryDependencies ++= Seq(
"org.virtuslab" %% "besom-kubernetes" % "0.0.1-beta", // or any other sdk you are using
"org.virtuslab" %% "besom-core" % "0.0.1-beta"
))
This just informs your IDE about the existence of the infrastructure module,
DO NOT remove dependencies from project.scala
, because they are necessary in both places.
Tips
- Pass
Context
everywhere you are using Pulumi, for example when you are creating a resource. - Resources are initialized lazily. To make them appear in your physical infrastructure make sure their evaluation is triggered directly or transitively from the main for-comprehension block of your Pulumi program.
- Use whatever scala concepts you are familiar with, infrastructure as code in Besom is still a scala program, so you have the full potential of the language to work with.
- Pay attention to the types. You will be instantiating case classes to pass parameters, note their package of origin.