Besom Scala SDK for Pulumi

Besom uses lazy semantics, meaning that declaring a resource in code does not automatically execute it. If a resource is not composed into the main program flow, it will not appear in your deployment plan (e.g., when running pulumi up).

A resource is considered "dangling" (and thus ignored) if it is:

• Never maped or flatMaped to derive another value.
• Not used by Stack() or exported via Stack.export.
• Never passed as an argument to another Resource.

To ensure a resource is evaluated, you can:

1. Pass it to the Stack constructor: Use this if the resource just needs to exist and you don't need its properties.
2. Compose it into exports or other resources: If you use its properties (via map) or pass its Output to another resource, Besom will implicitly pull it into the main flow.

Recommendation: To catch unused resources, enable the Scala compiler flag -Wunused:all.

import besom.*
import besom.api.aws

// This resource is dangling and will NOT be deployed
@main def main = Pulumi.run {
  val s3Bucket: Output[aws.s3.Bucket] = aws.s3.Bucket("my-bucket")
  
  Stack.exports()
}

// FIX 1: Pass to Stack to ensure evaluation
@main def main = Pulumi.run {
  val s3Bucket: Output[aws.s3.Bucket] = aws.s3.Bucket("my-bucket")
  Stack(s3Bucket) 
}

// FIX 2: Compose via mapping/exports
@main def main = Pulumi.run {
  val s3Bucket: Output[aws.s3.Bucket] = aws.s3.Bucket("my-bucket")
  Stack.exports(s3Url = s3Bucket.map(_.websiteEndpoint))
}

Inputs are specialized types used in resource constructors to facilitate configuration. They provide an elastic model that allows users to provide values in multiple formats, making it easier to define infrastructure resources.

An Input[A] can accept:

• Raw values of type A.
• Values wrapped in an Output[A].
• Nothing (when using Input.Optional[A]).

Input.Optional[A] can accept:

• Raw Option[A] (e.g., Some(value) or None).
• Output[Option[A]].
• Output[A] (which is automatically treated as Some in the context of the input).

val int1: Input[Int] = 23
val int2: Input[Int] = Output(23)

// Using Input.Optional
val maybeInt1: Input.Optional[Int] = 23
val maybeInt2: Input.Optional[Int] = None
val maybeInt3: Input.Optional[Int] = Some(23)
val maybeInt4: Input.Optional[Int] = Output(23)
val maybeInt5: Input.Optional[Int] = Output(Option(23))
val maybeInt6: Input.Optional[Int] = Output(None)

It is critical to distinguish between Resource constructors and plain Outputs when managing side effects:

• Resource Constructors are memoized: Pulumi requires that any given resource be declared only once. Besom handles this by caching calls to resource constructors with the same arguments. If you call a resource constructor multiple times with the same arguments, it returns the same resource instance and only executes the effect once.
• Plain Outputs are NOT memoized: If you wrap a side effect in a plain Output { ... } block, that effect will be executed every time the Output is referenced or evaluated in the program flow.

Best Practice: Always compose resource constructors into the main flow and avoid using plain Output blocks for side effects to prevent unexpected multiple executions.

import besom.*
import besom.api.aws

@main def main = Pulumi.run {
  val s3Bucket: Output[aws.s3.Bucket] = aws.s3.Bucket("my-bucket")
  // This side effect will run TWICE because it is a plain Output, not a Resource constructor
  val launchMissiles: Output[_] = Output { launch() }
  
  Stack(s3Bucket, launchMissiles)
    .export(
      url     = s3Bucket.map(_.websiteEndpoint),    
      fallout = launchMissiles
    )
}

Besom uses Scala's Context Functions to pass the Context implicitly. The Pulumi.run block provides this context automatically to any code inside it.

If you define functions outside of the Pulumi.run block that need to create resources or access stack configuration, you must explicitly declare the context using a using clause: (using Context) or (using besom.Context).

To ensure all user-facing types and functions are available, every Besom program file should include an import besom.* clause. If you are using a functional effect system, use the specific variant imports:

• Cats-Effect: import besom.cats.*
• ZIO: import besom.zio.*

Important Dependency Note: Always use org.virtuslab::besom-* dependencies. Besom is a separate implementation and does not depend on the com.pulumi:* Java SDK.

import besom.*

// Functions defined outside `Pulumi.run` must use the `(using Context)` clause
def deployPostgres(dbName: String)(using Context): Output[Postgres] =
  ...

@main def run = Pulumi.run {
  // Inside `Pulumi.run`, Context is provided implicitly
  val component = deployPostgres("my-db")

  Stack.exports(
    aComponentUrn = component.map(_.urn)
  )
}

Besom automatically detects the appropriate build tool (executor) based on the files present in your project directory. If use-executor is specified in Pulumi.yaml, it replaces the command used by the chosen executor but does not change the executor itself.

Important Notes:

• Scala CLI: Besom supports scala-cli or scala (for Scala 3.5+). If both are installed, you must disambiguate using use-executor in Pulumi.yaml or the BESOM_LANGHOST_SCALA_CLI_COMMAND environment variable.
• Wrappers: Besom prefers local wrappers (like ./gradlew) if they follow standard conventions. On Windows, it looks for .bat versions.
• Version 0.5.2+ Change: A local ./scala-cli script is no longer automatically picked up. Use BESOM_LANGHOST_SCALA_CLI_COMMAND=./scala-cli to point to it explicitly.