Introduction to Stacks

A stack is a definition file that describe an environment as code, written in JSON or YAML.

They are similar to a Docker compose file or Helm chart, in that they describe the deployment of multiple containers and their configurations, volumes, etc. but go beyond either of those formats by describing everything available within an environment on Cycle.

The Stack File

Stacks are written using JSON or YAML, and can either be uploaded directly using the Portal or Platform API , or by creating a cycle.json or cycle.yaml file in a git repository and using it as the stack source.

The stack file can describe every aspect of an environment, from the containers and their configurations, to the scoped variables, load balancer configurations and other service configurations in a single file.

Stacks can be used to deploy the same 'application' multiple times, or as deployments multiple times to the same environment.

Stack Spec

The stack spec defines what fields are available within a stack file.

Stack Spec

Stack Builds

A stack build is a deployable snapshot of a stack. It contains all the built images and configurations, and is deployed directly to an environment, or as a deployment within an existing environment. Stack builds are atomic and should hold everything they need to run correctly.

Deploying Stack Builds

When deploying a stack build, there are a few options available for how containers are treated in the target environment:

Reimage: If a container in the target environment matches a container in the stack and this option is enabled, the target container will be reimaged to the stack container's image.
Reconfigure: If a container in the target environment matches a container in the stack and this option is enabled, the target container's settings will be updated to match the settings defined in the stack.

These options can be set on a per-container basis.

There are a few options for scoped variables when deploying a stack build as well:

Add New: If a scoped variable is not found in the target environment and this option is enabled, it will be created.
Replace Existing: If a scoped variable defined in the stack matches the identifier of a scoped variable in the target environment and this option is enabled, the scoped variable will be updated to match the stack value.

Deployments

A stack build can be deployed as a new deployment within the environment. Using this pattern, as applications are updated, new builds can be generated and the build deployed, tested, and verified before promoting to production.

Build Logs

Every build will generate a build log that contains all the output generated when building the images associated with the stack.

Stack File Examples

{
  "version": "1.0",
  "scoped_variables": [
    {
      "identifier": "encrypted",
      "scope": {
        "containers": {
          "global": true
        }
      },
      "access": {
        "env_variable": {
          "key": "ENCRYPTED"
        },
        "internal_api": {},
        "file": {}
      },
      "source": {
        "type": "raw",
        "details": {
          "value": "4a2e78b5403700d9cdfb5510f6361bc4ddb4a4af111e6fe3a5b70a9d9875ba33a82c5b890fe131465a1a3cb38b99b8eb",
          "secret": {
            "iv": "u4L2w6Qcm3On3duuA4U+gA==",
            "hint": "e8e56823f631edf06d98499e1fd8cb5eedf028344d38d7087550ae917bd79fb3"
          },
          "blob": false
        }
      }
    },
    {
      "identifier": "stackone",
      "scope": {
        "containers": {
          "global": true
        }
      },
      "access": {
        "env_variable": {
          "key": "STACKONE"
        },
        "internal_api": {},
        "file": {}
      },
      "source": {
        "type": "raw",
        "details": {
          "value": "STACKONEVALUE",
          "secret": null,
          "blob": false
        }
      }
    },
    {
      "identifier": "urltype",
      "scope": {
        "containers": {
          "global": true
        }
      },
      "access": {
        "internal_api": {
          "duration": "15m"
        },
        "file": {
          "path": "/somepath/urltype.json",
          "decode": false
        }
      },
      "source": {
        "type": "url",
        "details": {
          "url": "https://someurl.com/config",
          "headers": { "X-Custom-Test-Header": "SOMEVALUE" },
          "auth_token_url": "https://someurl.com/auth"
        }
      }
    }
  ],
  "containers": {
    "demo": {
      "name": "demo",
      "image": {
        "name": "simplews",
        "origin": {
          "type": "docker-file",
          "details": {
            "context_dir": "/",
            "build_file": "/Dockerfile"
          }
        }
      },
      "config": {
        "network": {
          "public": "enable",
          "hostname": "simplews",
          "ports": ["80:80"]
        },
        "deploy": {
          "instances": 1
        }
      }
    },
    "remote": {
      "name": "remote",
      "image": {
        "name": "simplews-external",
        "origin": {
          "type": "docker-file",
          "details": {
            "repo": {
              "url": "https://github.com/username/repo.git"
            },
            "context_dir": "/",
            "build_file": "/Dockerfile"
          }
        }
      },
      "config": {
        "network": {
          "public": "enable",
          "hostname": "simplews",
          "ports": ["80:80"]
        },
        "deploy": {
          "instances": 1
        }
      }
    }
  }
}

{
  "version": "1.0",
  "services": {
    "discovery": {
      "service": {
        "high_availability": true,
        "auto_update": true,
        "enable": true
      },
      "config": {
        "hosts": {
          "somehost": {
            "ipv4": ["193.23.52.1"],
            "ipv6": []
          }
        }
      }
    },
    "loadbalancer": {
      "service": {
        "high_availability": true,
        "auto_update": true,
        "enable": true
      },
      "config": {
        "type": "v1",
        "ipv4": true,
        "ipv6": true,
        "details": {
          "controllers": {
            "1194": {
              "identifier": "default-1194",
              "transport": {
                "mode": "tcp",
                "config": {
                  "performance": false,
                  "ingress": {
                    "port": 1194,
                    "tls": null
                  },
                  "timeouts": {
                    "idle": "15m"
                  }
                },
                "routers": [
                  {
                    "match": {
                      "domains": null,
                      "internal_port": null
                    },
                    "mode": "round-robin",
                    "config": {
                      "sticky_sessions": true,
                      "destination_retries": 3,
                      "timeouts": {
                        "destination_connection": "3s"
                      }
                    }
                  }
                ]
              }
            },
            "443": {
              "identifier": "default-443",
              "transport": {
                "mode": "http",
                "config": {
                  "performance": false,
                  "ingress": {
                    "port": 443,
                    "tls": {
                      "enable": true,
                      "server_name": null,
                      "allow_insecure": null,
                      "client_auth": null
                    }
                  },
                  "timeouts": {
                    "idle": "60s"
                  },
                  "extension": {
                    "type": "http",
                    "details": {
                      "connections": {
                        "max_idle_conns_per_connection": 5
                      }
                    }
                  }
                },
                "routers": [
                  {
                    "match": {
                      "domains": null,
                      "internal_port": null
                    },
                    "mode": "round-robin",
                    "config": {
                      "sticky_sessions": true,
                      "destination_retries": 3,
                      "timeouts": {
                        "destination_connection": "3s"
                      },
                      "extension": {
                        "type": "http",
                        "details": {
                          "redirect": null,
                          "forward": {
                            "scheme": "http"
                          }
                        }
                      }
                    }
                  },
                  {
                    "match": {
                      "domains": null,
                      "internal_port": [443, 8443]
                    },
                    "mode": "round-robin",
                    "config": {
                      "sticky_sessions": true,
                      "destination_retries": 3,
                      "timeouts": {
                        "destination_connection": "3s"
                      },
                      "extension": {
                        "type": "http",
                        "details": {
                          "redirect": null,
                          "forward": {
                            "scheme": "https"
                          }
                        }
                      }
                    }
                  }
                ]
              }
            },
            "80": {
              "identifier": "default-80",
              "transport": {
                "mode": "http",
                "config": {
                  "performance": false,
                  "ingress": {
                    "port": 80,
                    "tls": null
                  },
                  "timeouts": {
                    "idle": "60s"
                  },
                  "extension": {
                    "type": "http",
                    "details": {
                      "connections": {
                        "max_idle_conns_per_connection": 5
                      }
                    }
                  }
                },
                "routers": [
                  {
                    "match": {
                      "domains": null,
                      "internal_port": [80]
                    },
                    "mode": "round-robin",
                    "config": {
                      "sticky_sessions": true,
                      "destination_retries": 3,
                      "timeouts": {
                        "destination_connection": "3s"
                      },
                      "extension": {
                        "type": "http",
                        "details": {
                          "redirect": {
                            "auto_https_redirect": true,
                            "port": null,
                            "scheme": null,
                            "url": null
                          },
                          "forward": {
                            "scheme": "http"
                          }
                        }
                      }
                    }
                  },
                  {
                    "match": {
                      "domains": null,
                      "internal_port": [443, 8443]
                    },
                    "mode": "round-robin",
                    "config": {
                      "sticky_sessions": true,
                      "destination_retries": 3,
                      "timeouts": {
                        "destination_connection": "3s"
                      },
                      "extension": {
                        "type": "http",
                        "details": {
                          "redirect": null,
                          "forward": {
                            "scheme": "https"
                          }
                        }
                      }
                    }
                  }
                ]
              }
            },
            "8812": {
              "identifier": "default-8812",
              "transport": {
                "mode": "tcp",
                "config": {
                  "performance": false,
                  "ingress": {
                    "port": 8812,
                    "tls": null
                  },
                  "timeouts": {
                    "idle": "20s"
                  }
                },
                "routers": [
                  {
                    "match": {
                      "domains": null,
                      "internal_port": null
                    },
                    "mode": "round-robin",
                    "config": {
                      "sticky_sessions": false,
                      "destination_retries": 3,
                      "timeouts": {
                        "destination_connection": "3s"
                      }
                    }
                  }
                ]
              }
            }
          }
        }
      }
    },
    "scheduler": {
      "config": {
        "access_keys": [
          { "ips": [], "name": "somekey", "secret": "supersecretkeyphrase" }
        ],
        "public": false
      },
      "service": {
        "auto_update": true,
        "enable": true,
        "high_availability": true
      }
    },
    "vpn": {
        "config": {
            "allow_internet": true,
            "auth": {
                "cycle_accounts": true,
                "vpn_accounts": true,
                "webhook": "https://someendpoint.com/auth"
            }
        },
        "service": {
            "enable": true,
            "auto_update": true,
            "high_availability": false
        }
    }
  },
  "containers": {}
}

Access Control Lists

Stacks support ACLs.

Get Started with Stacks

Get started by creating and deploying stacks using one of the interface-specific guides: