Repository files navigation

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, Besom is Scala SDK that allows you to write Pulumi programs in Scala, incidentally.

Besom Scala SDK for Pulumi lets you leverage the full power ofPulumi Infrastructure as Code Platformusing the Scala programming language. Scala support is currently inPublic Beta.

Pulumi is a registered trademark ofPulumi Corporation.

• Get Started with Besom: Deploy a simple application in AWS, Azure, Google Cloud or Kubernetes using Besom to describe the desired infrastructure using Scala.

• Besom Docs: Learn about Besom concepts, follow user-guides, and consult the reference documentation.

• Examples: Browse Scala examples across many clouds and scenarios including containers, serverless,and infrastructure.

1. Install Pulumi CLI:

   To install the latest Pulumi release, run the following (see fullinstallation instructions for additional installation options):

   curl -fsSL https://get.pulumi.com/| sh

2. Install Scala CLI:

   To install the latest Scala CLI release, run the following (seeinstallation instructions for additional installation options):

   curl -sSLf https://scala-cli.virtuslab.org/get| sh

3. Install Scala Language Plugin in Pulumi:

   To install the latest Scala Language Plugin release, run the following:

   pulumi plugin install language scala 0.3.2 --server github://api.github.com/VirtusLab/besom

4. Create a new project:

   You can start writing your Besom code at this point, but to help you set upBesom comes withPulumi templates.

   You can get started with thepulumi new command:

   mkdir besom-demo&&cd besom-demo

   pulumi new https://github.com/VirtusLab/besom/tree/v0.3.2/templates/aws

5. Deploy to the Cloud:

   Runpulumi up to get your code to the cloud:

   pulumi up

   This makes all cloud resources declared in your code. Simply makeedits to your project, and subsequentpulumi ups will computethe minimal diff to deploy your changes.

6. Use Your Program:

   Now that your code is deployed, you can interact with it. In theabove example, we can find the name of the newly provisioned S3bucket:

   pulumi stack output bucketName

7. Destroy your Resources:

   After you're done, you can remove all resources created by your program:

   pulumi destroy -y

To learn more, head over tovirtuslab.github.io/besom for much more information, includingtutorial,examples,andarchitecture and programming model concepts.

Pulumi.yaml is your main Pulumi file, explainedhere.

project.scala is the file containing your dependencies forScala-CLI.

Main.scala is the entry point for your Infrastructure as Code.

Resources created inPulumi.run { ... } block will be created by Pulumi.

A simple example using Scala CLI:

//>usingscala"3.3.1"//>usingplugin"org.virtuslab::besom-compiler-plugin:0.3.2"//>usingdep"org.virtuslab::besom-core:0.3.2"//>usingdep"org.virtuslab::besom-aws:6.31.0-core.0.3"importbesom.*importbesom.api.aws@maindefrun=Pulumi.run {valbucket= aws.s3.Bucket("my-bucket")Stack.exports(      bucketName= bucket.bucket   )}

• Resources are initialized lazily. To make them appear in your physical infrastructure make suretheir evaluation is triggered directly or transitively (by referencing them or resources that depend on them) byincluding them in the finalStack structure of your 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.
• Some Pulumi functions that allow you to access the metadata of the current stack require access to theContext.Context is available as a given (implicitly) in thePulumi.run block, but you can also require it explicitlyin any of your functions with(using Context).

• JDK 11 or higher is required
• Scala 3.3.1 or higher is required

Scala CLI is the recommended build tool, other tools are alsosupported. Besom will recognize Scala CLI and SBT programsand automatically recompile them without any further configuration.The supported versions are:

• Scala CLI 1.0.4 or higher
• SBT 1.9.6 or higher
• Apache Maven 3.8.4 or higher
• Gradle Build Tool 7.4 or higher

Other build tools are supported via theruntime.options.binaryconfiguration option that can point to a pre-built jar inPulumi.yaml, e.g.:

name:myprojectruntime:name:scalaoptions:binary:target/myproject-1.0-SNAPSHOT-jar-with-dependencies.jar

Besom usesScala-CLI for project compilation and execution.

To set up IDE support for an infrastructural project using Besom execute this commandinside the directory in which Besom project files exist:

scala-cli setup-ide.

As a result of this command, a.bsp directory will be created inside the project directory.

When opened, bothIntellij IDEAandMetals should automatically recognizethe project and set up the IDE accordingly.

sbt,gradle andmaven are also supported out-of-the-box,but arenot recommended due to slower iteration speed.Use ofsbt,gradle ormvn support is suggested for situations where managed infrastructureis being added to an already existing project that uses sbt as the main build tool.

IDE setup forsbt,gradle ormvn works automatically with both Intellij IDEA and Metals.

Mill is not yet supported.

VisitCONTRIBUTING.md for information on building Besom from source or contributing improvements.