Package: unfurl
IntroductionUnfurl is a command line tool for managing your DevOps infrastructure. Unfurl lets you easily track configuration, secrets, software and code dependencies, and deployment history all in git.Unfurl can integrate with the DevOps tools you are already using -- like Terraform, Ansible, and Helm -- allowing you to encapsulate your DevOps processes into reusable building blocks and describe your cloud infrastructure in simple, application-centric terms.Our VisionThe ultimate goal of Unfurl is enable anyone to clone, fork, and deploy live cloud services as easily as cloning and building code from git. So that we can have:Fully-functional and reproducible archives of web applications.Location independence to decentralize cloud infrastructure.Cooperatively build and run cloud services the same way we build open source software.How it works1. Useunfurl initto create an Unfurl-managed git repository. Or useunfurl cloneto clone an existing one.2. The repository will contain a few YAML files that you can edit. They will describe everything you'll need to deploy your application, such as:Cloud provider and SaaS services account credentials and other secrets organized into environments.Code repositories and container image registries.A high-level model of your cloud infrastructure and their dependencies such as compute instances and databases, described using theOASIS TOSCA(Topology and Orchestration Specification for Cloud Applications) standard.Operations that invoke Terraform, Ansible, or other command-line tools (which Unfurl can automatically install).3. Useunfurl deployto deploy the infrastructure. Unfurl will generate a plan based on your target environment and high-level model and choose the correct operations to call. It will commit to git the latest configuration and a history of changes to your cloud accounts.4. Now you have a reproducible description of your cloud infrastructure stored in git! So you can:Push your repository to a git service such as Github or Gitlab to share it. For access control, each environment can be stored as separate git submodules or branches.Pull incoming changes and review and approve pull requests before deploying.Clone the repository and deploy to new environments even if they use different services -- because your model is adaptable, manual changes are minimized.FeaturesNo server, agentlessSimple, stand-alone CLI that can be used both in your local development environment or in an automated CI/CD pipeline.Deploy infrastructure from simple, application-centric descriptionsModel your cloud infrastructure with theOASIS TOSCA(Topology and Orchestration Specification for Cloud Applications) standard either in YAML orPython.Import reusable and adaptable components or build (and publish) your own.Easily declare dependencies to enable incremental deployment.Path-based query DSL to express dynamic relationships between resources and configurations.Ansible-compatible Jinja2 templates provide an extensive, mature templating library.Dynamic matching and substitution so models can adapt to different environments, services and cloud providers.Integrates with the DevOps tools you are already usingIncludes out-of-the box support for:TerraformAnsibleshellHelmOctodnsKubernetesDockerSupervisorPlugin interface for adding your own.API for dynamic configuration enables full control over plan generation.Developer-friendly state managementAll resource state is stored in git as human-readable and editable, application-centric resource stateYou so can easily override or repair resource representations enabling interactive development.Editor friendly config files:Comments, order, and whitespace are preserved.Syntactic macros for YAML provide generic facility for re-use and avoiding verbose boiler-plate.Zero installationManage your local machine and bootstrap setup by deploying locally.Downloads and installs specified software versions and code as deployment process.Creates and manages isolated deployment environments.Isolated environments can be either a Docker container or a Python virtualenv withasdf.Clear separation of local and shared configuration to avoid unnecessary local configuration steps.Flexible Secrets ManagementDeclare secrets and protect your repository.Inline encryption or use external secret managers like HashiCorp Vault.Automatic encryption of files insecretsfolders.Sensitive content redacted in output and logs"Day Two" OperationsCheck, discover, and repair commandsDefine your own workflows for maintenance tasks like backup and restore.Installationunfurlis available onPyPI. You can install usingpip(orpip3):pip install unfurlRunningunfurl home --initcreates a virtual Python environment to run unfurl in so by default unfurl only installs the minimal requirements needed to run the command line. If you want to run unfurl using your system Python install it with the "full" option:pip install unfurl[full]You can also installunfurldirectly from this repository to get the latest code:pip3 install "git+https://github.com/onecommons/unfurl.git#egg=unfurl"Alternatively, you can use theUnfurl container on Docker Hub:docker run --rm -it -v $(pwd):/data -w /data onecommons/unfurl:stable unfurl ...Thestabletag matches the version published to PyPi;latestis the latest code from the repository.RequirementsLinux or MacOSGitPython (3.7, 3.8, 3.9, 3.10, 3.11, 3.12)Optional: Docker or PodmanShell autocompleteUse the table below to activate shell autocompletion for theunfurl:ShellInstructionsBashAdd this to~/.bashrc:eval "$(_UNFURL_COMPLETE=bash_source unfurl)"ZshAdd this to~/.zshrc:eval "$(_UNFURL_COMPLETE=zsh_source unfurl)"FishAdd this to~/.config/fish/completions/unfurl.fish:eval (env _UNFURL_COMPLETE=fish_source unfurl)Developinggit clone --recurse-submodules https://github.com/onecommons/unfurlTo build documentation: Runtox -e docs.To build a distribution package run:python setup.py sdist bdist_wheelYou can now install this package with pip, for example:pip install ./dist/unfurl-0.2.2.dev3-py2.py3-none-any.whlRunning unit testsYou can usetoxto run the unit tests inside the supported python environments with the latest source installed.
Install toxpip install tox==3.28.0and then runtoxin source root. To install the dependencies you may need header files installed by the following OS packages:python-dev,libcrypt-dev,openssl-dev. (Note: if installation of a dependency fails, reinvoketoxwith-rto recreate the test environment.)
If you useasdfto manage multiple versions of Python, also installtox-asdf:pip install tox-asdf.Arguments after--are passed to the test runner, e.g. to run an individual test:tox -- tests/test_runtime.py.Status and CaveatsBe mindful of these limitations:Only clone and deploy trusted repositories and projects. The docker runtime is not configured to provide isolation so you should assume any project may contain executable code that can gain full access to your system.Locking to prevent multiple instances of Unfurl from modifying the same resources at the same time currently only works with instances accessing the same local copy of an ensemble.Incremental updates are only partially implemented. You can incrementally update an ensemble by explicitly limiting jobs with the--forceand--instancecommand line options.Unfurl CloudThe best way to manage your Unfurl project is to useUnfurl Cloud, our open-source platform for collaboratively developing cloud applications.Get StartedCheck out the rest of Unfurl's documentationhere. Release notes can be foundhere.