DOCSEARCHbyAlgolia
Submit Docs

Cloud Foundry Deployment

repository·main·Indexed 43 days ago

https://github.com/cloudfoundry/cf-deployment

Canonical BOSH deployment manifests for the Cloud Foundry Application Runtime. Provides secure, readable, and configurable manifests and IaaS support for deploying Cloud Foundry on Alibaba Cloud, OpenStack, BOSH Lite, vSphere, AWS, and GCP.

Tokens
24.4K
Snippets
41
Records
80
Agent score
52%

What's inside cf-deployment

  1. Access community-supported ops-files

    main

    The operations/community/ directory contains a collection of ops-files submitted by the Cloud Foundry community.

    Warning: These files are not supported or tested by the Release Integration team. Users are responsible for verifying these files before use. If you encounter issues, you should contact the specific maintainer listed for that file rather than the core cf-deployment maintainers.

  2. Understand the purpose and design of cf-deployment

    main

    The cf-deployment repository provides a canonical BOSH deployment manifest for the Cloud Foundry Application Runtime. It relies on individual component releases and utilizes modern BOSH director and CLI features.

    Key Design Principles:

    • Readability: Only necessary configuration is included to keep manifests human-readable.
    • Security by Default: Uses CredHub for strong passwords, certificates, and keys. TLS/SSL is enabled on every job that supports it. There are no default credentials, even in bosh-lite.
    • Redundancy: Uses two Availability Zones (AZs) for most instance groups.
    • Diego by Default: Uses the Diego architecture for the runtime.
    • Persistence: Uses singleton versions of the PXC release for databases and the CAPI release's singleton WebDAV job for blob storage.
    • Load Balancing: Assumes load-balancing is handled by the IaaS or an external deployment.

  3. Identify breaking changes in major versions

    main

    A major version bump is triggered when changes affect the operator's ability to deploy without manual intervention. While not an exhaustive list, the following are considered breaking changes:

    • Downtime: Any change that causes application or operator downtime.
    • Manifest Structure Changes: Modifying, deleting, or moving the name of a job or instance group in the main manifest, or modifying/deleting a property of a job or instance group.
    • Credential Changes: Changing the name of credentials in the main manifest.
    • Manual Intervention: Any change requiring out-of-band manual steps from the operator.
    • Ops-file Path/Type Changes: Modifying the path, type, values, or removing ops-files in these specific directories:
      • ./operations/ or ./operations/experimental
      • ./addons
      • ./backup-and-restore/

    Note on skipping versions: Since v32.x.x, you must not skip major versions when updating. Skipping a major version means a seamless update is no longer guaranteed, as some features (like complex database migrations) require step-by-step rollouts.

  4. Configure Databases and Blobstores in CF-Deployment

    main

    CF-Deployment provides default configurations that can be overridden using ops-files:

    Databases

    • Default: MySQL Galera (singletons). Scale using operations/scale-database-cluster.yml.
    • External Databases: To use services like Amazon RDS or Google Cloud SQL, use the use-external-dbs.yml ops-file.
    • Supported: MySQL 8.0 (via pxc-release), PostgreSQL 17 (via postgres-release), and GCP Cloud SQL for MySQL 8.0.

    Blobstores

    • Default: webdav (singleton, cannot be scaled).
    • External Blobstores: To use Amazon S3, Google Cloud Storage, Azure Blob storage, or OpenStack Swift, use the appropriate ops-files found in the operations README.

  5. Manage deployment defaults and overrides

    main

    Certain values in deployment manifests (such as usernames, instance counts, deployment names, or network names) often have standard defaults but require overrides for specific environments.

    Operators can manage these using:

    1. Ops-files: Used to mutate values in the deployment manifest.
    2. Variable-ization: Making values like network_name configurable via variables so that ops-files do not rely on hardcoded names like default.

  6. Handle ops-file conflicts and reuse

    main

    When using multiple ops-files, operators may encounter conflicts where one ops-file mutates a layer that another ops-file depends on (e.g., swapping MySQL for Postgres).

    Common challenges include:

    • Ordering: The order in which ops-files are applied significantly impacts the final state. It is difficult to trace which ops-file overrode which attribute.
    • Logic Duplication: Similar logic (like scaling down instances) is often duplicated across different ops-files (e.g., bosh-lite.yml and scale-to-one-az.yml).
    • Injection: Currently, adding an instance group typically requires appending to the end of an array, which can break BOSH's ordered deployment requirements. A move operation or index-based injection is needed to change job topology or colocation.

  7. Standardize BOSH links for cross-release configuration

    main

    BOSH links are used to share configuration (like ports or credentials) between releases. However, different releases often use different property names for the same concept (e.g., cf_mysql.mysql.port vs databases.port), making it difficult to consume them via a standard link type.

    A proposed solution is to allow renaming properties within a link definition so that consumers can use a consistent interface. This would allow a database link type to have a standardized port property regardless of the underlying release structure.

    - name: mysql-database
  type: database
  properties:
  - name: port
    source: cf_mysql.mysql.port

  8. Understand CF-Deployment test types

    main

    The unit test suites in cf-deployment utilize several types of tests to ensure quality:

    • EnsureTestCoverage: Ensures every operations file in a subdirectory has at least one InterpolateTest.
    • ReadmeTest: Ensures every operations file in a subdirectory has a corresponding README entry.
    • InterpolateTest: Validates that bosh interpolate runs successfully against cf-deployment.yml using the specified configuration.
    • semantic_test: A specialized suite that runs tests across all subdirectories to catch semantic errors.

  9. Customize deployment using Ops Files

    main

    While cf-deployment.yml provides a secure and functional default, you can modify the configuration using the -o or --ops-file flag. Ops files are .yml files that detail operations to be performed on the manifest before variables are processed.

    Available Ops File Categories:

    • Addons (operations/addons): Changes to most or all instance groups (e.g., configuring rsyslog).
    • Community (operations/community): Community-contributed configurations (not maintained by the Release Integration team).
    • Experimental (operations/experimental): Configurations being validated for future inclusion in the base manifest.
    • Test (operations/test): Configurations used in the CI pipeline.
    • Backup and Restore (operations/backup-and-restore): Configurations for BOSH Backup and Restore (BBR).
    bosh deploy cf-deployment.yml -o operations/addons/some-addon.yml

  10. Understand the cf-deployment versioning scheme

    main

    cf-deployment uses a modified version of Semantic Versioning designed to help Cloud Foundry operators automate deployments. The versioning scheme communicates whether an update can be performed automatically or if it requires manual intervention.

    • Major versions: Indicate breaking changes that require manual operator steps or cause downtime.
    • Minor versions: Indicate backwards-compatible additions (e.g., new features, stemcell updates, or new ops-files) that can be deployed automatically.
    • Patch versions: Indicate backwards-compatible bug fixes. Note that bug fixes are often bundled into minor releases rather than released as standalone patches.

  11. Persist the BBL state directory

    main

    Every successful bbl command creates or updates a directory containing bbl-state.json and other critical files. This directory is either the current working directory, the directory specified by --state-dir, or the directory pointed to by the $BBL_STATE_DIR environment variable.

    You must persist this directory. A common pattern (used by CF-Deployment-Concourse-Tasks) is to check this directory into a private git repository.

  12. BOSH Job Spec standards for cf-deployment

    main

    When authoring BOSH releases for cf-deployment, job specifications (specs) must follow specific standards to ensure consistency across multiple teams and tools. These standards govern how defaults, descriptions, names, and paths are defined.

    Key Principles

    • Defaults and Standalone Operation: Job specs should contain appropriate defaults that allow the release to operate correctly in a standalone deployment. However, for Cloud Foundry environments, cf-deployment will override these defaults with CF-specific values.
    • Credential Security: Job specs must not specify default values for any credentials.
    • Property Descriptions: Descriptions for properties within a spec should explicitly include constraints on the allowed values for that property.
    • Namespacing: New properties should not be namespaced to their specific job.
    • TLS Property Naming: New TLS properties must match the Credhub data structure used for certificates.
    • Versioning and API: Job specs are considered part of the BOSH release's API. Changes to the structure or required properties of a spec can impact versioning requirements.