Class DeploymentPlan

java.lang.Object
com.eqixiac.equinix.design.optimizer.wizard.model.DeploymentPlan
public class DeploymentPlan extends Object
A deployment plan produced by the Deployment Wizard: the Cloud Routers, provider connections, backbone links and routing protocols to create, the native multicloud links and Fabric Interconnects the design relies on but the SDK does not create, pricing, and the layered validation state.

Plan as data

A plan is an immutable value. Every planned resource carries a stable logical key derived from the design (for example router/DC, connection/DC/aws, backbone/DC-NY, connection/DC/aws/rp/BGP), so the same design produces the same keys whatever the name prefix. The plan records the DesignSpec fingerprint it was derived from (getSpecFingerprint()), and planId() is a hash of what it would build. It round-trips through JSON (toJson(), fromJson(String), save(Path), load(Path)); a loaded plan has no Fabric client until withFabric(FabricGateway) binds one.

Lifecycle

DeploymentPlan plan = fabric.deploymentWizard(result).projectId(project).notifications("noc@example.com").plan();
plan.save(Path.of("plan.json"));

PlanDiff drift = plan.diff();                                       // read-only
DeploymentOutcome out = plan.reconcile(inputs, ExecutionOptions.defaults(),
        new FileCheckpointStore(Path.of(".checkpoints")));          // creates only what is missing

execute(ExecutionInputs, ExecutionOptions) provisions the whole plan in one run; reconcile(ExecutionInputs, ExecutionOptions, CheckpointStore) reads live state first, adopts what exists, creates the rest and checkpoints after every step, so it can be re-run after a crash or abort without creating duplicates. Both follow one failure policy (ExecutionOptions.failurePolicy): abort and roll back by default, or continue and report partial state. See PlanExecutor.

Beta. multicloudLinks are native provider-to-provider links between two clouds, which use no Equinix resource. The plan carries and prices them; execution never provisions them, totalResourceCount() excludes them, and their cost is never part of the Equinix totals.

  • Constructor Details

    • DeploymentPlan

      public DeploymentPlan()

  • Method Details

    • planId

      public String planId()
      The plan's content identity: a hash of what it would build (resources, Interconnects, native links, deployment name, prefix, project, spec fingerprint), not of pricing or validation state.
      Returns:
      16 lowercase hex characters
      See Also:

    • getSchemaVersion

      public String getSchemaVersion()
      The plan document format version.
      Returns:
      "1"

    • getPlanId

      public String getPlanId()
      The id as a bean property, so it is written into the plan document.
      Returns:
      planId()

    • effectiveDeploymentName

      public String effectiveDeploymentName()
      The deployment name, or plan-<planId> for a hand-built plan that has none. Checkpoints and connection markers use this value.
      Returns:
      a non-null deployment identity

    • multicloudLinksOrEmpty

      public List<PlannedMulticloudInterconnect> multicloudLinksOrEmpty()
      The native multicloud links on the plan, never null.
      Returns:
      getMulticloudLinks(), or an empty list when that is null

    • interconnectsOrEmpty

      public List<PlannedInterconnect> interconnectsOrEmpty()
      The Fabric Interconnects on the plan, never null.
      Returns:
      getInterconnects(), or an empty list when that is null

    • totalResourceCount

      public int totalResourceCount()
      Total number of resources execution creates: Cloud Routers, provider connections, backbone links and routing protocols. Native multicloud links and Interconnects are excluded.
      Returns:
      the count

    • toSummary

      public String toSummary()
      A concise plain-text summary.
      Returns:
      the summary

    • toMarkdown

      public String toMarkdown()
      A full Markdown report: identity, validation state, required inputs, every planned resource, native links, Interconnects, cost estimate and execution order.
      Returns:
      Markdown

    • toJson

      public String toJson()
      This plan as an indented JSON document, including planId and schemaVersion.
      Returns:
      JSON

    • fromJson

      public static DeploymentPlan fromJson(String json)
      Parses a plan document written by toJson().
      Parameters:
      json - the document
      Returns:
      the plan, with no Fabric client bound
      Throws:
      IllegalArgumentException - when unreadable or when its planId does not match its content

    • save

      public void save(Path file)
      Writes this plan to a file (atomically).
      Parameters:
      file - the destination

    • load

      public static DeploymentPlan load(Path file)
      Reads a plan from a file written by save(Path).
      Parameters:
      file - the file
      Returns:
      the plan, with no Fabric client bound

    • withFabric

      public DeploymentPlan withFabric(FabricGateway fabric)
      This plan with a Fabric client bound (needed after load(Path) before any live call).
      Parameters:
      fabric - the Fabric client
      Returns:
      a copy bound to fabric

    • valueRealization

      public PlanValueAssessment valueRealization()
      Begins a value-realization assessment of this plan: declare your per-provider monthly egress volumes and get back the egress savings the plan's private interconnects produce.
      Returns:
      a PlanValueAssessment builder for declaring egress volumes

    • dryRun

      public DeploymentPlan dryRun()
      Re-runs the layered plan-time validation (structural and catalog checks, live Cloud Router dry-run, connection endpoint dispatch) and returns a new plan with the refreshed status. Nothing is provisioned. A live step that cannot be attempted is recorded as a skipped validation with a reason; only a genuine rejection is an error. On a loaded plan (no source optimization) the new-market checks that need the optimizer's recommendations are not run.
      Returns:
      a new plan with refreshed validity, deferred and skipped validations, and required inputs

    • diff

      public PlanDiff diff()
      Compares the plan with live Fabric state (read-only): one verdict per planned resource (MISSING, PRESENT_MATCHING, PRESENT_DIFFERENT with the differing fields, UNREADABLE, NOT_EXECUTABLE) and the live resources that carry the plan's marker but are not in it.
      Returns:
      the diff
      Throws:
      IllegalStateException - when no Fabric client is bound

    • diff

      public PlanDiff diff(CheckpointStore store)
      As diff(), also matching resources by the uuids recorded in a checkpoint store.
      Parameters:
      store - the checkpoint store, or null
      Returns:
      the diff
      Throws:
      IllegalStateException - when no Fabric client is bound

    • execute

      public DeploymentOutcome execute()
      Executes the plan with no customer inputs and default options. See execute(ExecutionInputs, ExecutionOptions).
      Returns:
      the outcome

    • execute

      public DeploymentOutcome execute(ExecutionInputs inputs)
      Executes the plan with default options. See execute(ExecutionInputs, ExecutionOptions).
      Parameters:
      inputs - the per-connection authorization keys, VLAN tags and Azure peering types
      Returns:
      the outcome

    • execute

      public DeploymentOutcome execute(ExecutionInputs inputs, ExecutionOptions options)
      Provisions the whole plan in one run (no live-state read; use reconcile(ExecutionInputs, ExecutionOptions, CheckpointStore) for an idempotent, resumable run). Order, pre-flight, the failure policy and rollback are described on PlanExecutor. A provider connection that needs a cloud authorization key the plan and the inputs do not supply fails the run before anything is sent.
      Parameters:
      inputs - the customer inputs; null means none
      options - execution options; null means defaults
      Returns:
      the outcome, with every step, error and (after an abort) the rollback report
      Throws:
      IllegalStateException - if the plan is not valid (the message lists the errors) or has no Fabric client

    • reconcile

      public DeploymentOutcome reconcile(ExecutionInputs inputs, ExecutionOptions options, CheckpointStore store)
      Brings live state to the plan, creating only what is missing and checkpointing after every step; see PlanExecutor.reconcile(DeploymentPlan, ExecutionInputs, ExecutionOptions, CheckpointStore).
      Parameters:
      inputs - the customer inputs; null means none
      options - execution options (dry run, failure policy, opt-in updates); null means defaults
      store - the checkpoint store; null means a fresh in-memory store
      Returns:
      the outcome
      Throws:
      IllegalStateException - if the plan is not valid or has no Fabric client

    • rollback

      public RollbackReport rollback(DeploymentOutcome outcome)
      Removes what an earlier run created: connections first, each polled to DEPROVISIONED or 404 within the default delete timeout, then the Cloud Routers whose connections are all gone. Everything that could not be removed is listed as an orphan with its uuid.
      Parameters:
      outcome - the outcome of execute() or reconcile(ExecutionInputs, ExecutionOptions, CheckpointStore)
      Returns:
      the rollback report

    • rollback

      public RollbackReport rollback(DeploymentOutcome outcome, ExecutionOptions options)
      As rollback(DeploymentOutcome) with explicit timeouts, poll interval and clock.
      Parameters:
      outcome - the outcome to undo; null is a no-op
      options - timeouts, poll interval and clock
      Returns:
      the rollback report