Test Documentation Release 8 Sam December 01, 2015 Contents 1 Overview 3 1.1 The CloudSlang Project.........................................3 1.2 Get Started................................................4 2 CloudSlang 7 2.1 Content..................................................7 2.2 Hello World...............................................7 2.3 YAML Overview.............................................9 2.4 DSL Reference.............................................. 10 2.5 Examples................................................. 31 2.6 Tests................................................... 40 2.7 Best Practices............................................... 42 2.8 CLI.................................................... 44 2.9 Build Tool................................................ 49 2.10 CloudSlang Editors............................................ 50 3 Developer 51 3.1 Developer Overview........................................... 51 3.2 CloudSlang................................................ 51 3.3 Embedded Engine............................................ 56 3.4 Score API................................................. 59 3.5 Score Events............................................... 62 3.6 Architecture............................................... 62 3.7 Contributions............................................... 67 4 Tutorial 73 4.1 Lesson 1 - Introduction and Setup.................................... 73 4.2 Lesson 2 - First Operation........................................ 75 4.3 Lesson 3 - First Flow........................................... 77 4.4 Lesson 4 - Outputs and Results..................................... 79 4.5 Lesson 5 - Default Navigation...................................... 82 4.6 Lesson 6 - Handling Failure Results................................... 84 4.7 Lesson 7 - Custom Navigation...................................... 85 4.8 Lesson 8 - Input Parameters....................................... 88 4.9 Lesson 9 - Subflows........................................... 93 4.10 Lesson 10 - For Loop.......................................... 98 4.11 Lesson 11 - Loop Aggregation...................................... 102 4.12 Lesson 12 - Existing Content...................................... 106 i 4.13 Lesson 13 - System Properties...................................... 109 4.14 Lesson 14 - 3rd Party Python Packages................................. 114 4.15 Lesson 15 - Asynchronous Loop..................................... 119 ii Test Documentation, Release 8 Contents: Contents 1 Test Documentation, Release 8 2 Contents CHAPTER 1 Overview Contents: 1.1 The CloudSlang Project CloudSlang is a flow-based orchestration tool for managing deployed applications. It allows you to rapidly automate your DevOps and everyday IT operations use cases using ready-made workflows or create custom workflows using a YAML-based DSL. The CloudSlang project is composed of three main parts: the CloudSlang Orchestration Engine, the CloudSlang language and the ready-made CloudSlang content. 1.1.1 CloudSlang Orchestration Engine The CloudSlang Orchestration Engine is packaged as a lightweight Java .jar file and can therefore be embedded into existing Java projects. The engine can support additional workflow languages by adding a compiler that translates the workflow DSL into the engine’s generic workflow execution plans. 1.1.2 CloudSlang Language The CloudSlang language is a YAML-based DSL for writing workflows. Using CloudSlang you can define a workflow in a structured, easy-to-understand format that can be run by an embedded instance of the CloudSlang Orchestration Engine or the stand-alone CloudSlang CLI. The CloudSlang language is simple and elegant, yet immensely powerful at the same time. There are two main types of CloudSlang content, operations and flows. An operation contains an action, which can be written in Python or Java. Operations perform the “work” part of the workflow. A flow contains tasks, which stitch together the actions performed by operations, navigating and passing data from one to the other based on operation results and outputs. Flows perform the “flow” part of the workflow. 1.1.3 CloudSlang Ready-Made Content Although writing your own CloudSlang content is easy, in many cases you don’t even need to write a single line of code to leverage the power of CloudSlang. The CloudSlang team has already written a rich repository of ready-made content to perform common tasks as well as content that integrates with many of today’s hottest technologies, such 3 Test Documentation, Release 8 as Docker and CoreOS. And, the open source nature of the project means that you’ll be able to reuse and repurpose content shared by the community. 1.1.4 CloudSlang Features CloudSlang and its orchestration engine are: • Process Based: allowing you to define the ‘how’ and not just the ‘what’ to better control the runtime behavior of your workflows. • Agentless: there are no agents to set up and manage on all your machines. Instead, workflows use remote APIs to run tasks. • Scalable: execution logic and distribution are optimized for high throughput and are horizontally scalable. • Embeddable: the CloudSlang Orchestration Engine is distributed as a standard java library, allowing you to embed it and run CloudSlang from your own applications. • Content Rich: you can build your own flows, or just use CloudSlang ready-made content. 1.2 Get Started It’s easy to get started running CloudSlang flows, especially using the CLI and ready-made content. 1.2.1 Download, Unzip and Run • Download the CLI zip file. • Unzip the archive. • Run the CloudSlang executable. • At the prompt enter: run --f ../content/io/cloudslang/base/print/print_text.sl --i text=Hi • The CLI will run the ready-made print_text operation that will print the value passed to the variable text to the screen. 1.2.2 Docker • docker pull cloudslang/cloudslang • docker run -it cloudslang/cloudslang • At the prompt enter: run --f ../content/io/cloudslang/base/print/print_text.sl --i text=Hi Or, to run the flow without the prompt: docker run --rm -ti cloudslang run --f ../content/io/cloudslang/base/print/print_text.sl --i text=first_flow • The CLI will run the ready-made print_text operation that will print the value passed to the variable text to the screen. 4 Chapter 1. Overview Test Documentation, Release 8 1.2.3 Next Steps Now that you’ve run your first CloudSlang file, you might want to: • Learn how to write a print operation yourself using the Hello World example. • Learn about the language features using the New Hire Tutorial. • Learn about the language in detail using the CloudSlang Reference. • See an overview of the ready-made content. • Learn about the ready-made content. • Learn about embedding CloudSlang or the CloudSlang Orchestration Engine into your existing application. • Learn about the architecture of CloudSlang and the CloudSlang Orchestration Engine. 1.2. Get Started 5 Test Documentation, Release 8 6 Chapter 1. Overview CHAPTER 2 CloudSlang Contents: 2.1 Content Ready-made CloudSlang content is hosted on GitHub in the cloud-slang-content repository. The repository contains CloudSlang content written by the CloudSlang team as well as content contributed by the community. The cloud-slang-content repository contains ready-made CloudSlang flows and operations for many common tasks as well as content that integrates with several other systems. The repository may contain some beta content. Beta content is not verified or tested by the CloudSlang team. Beta content is named with the beta_ prefix. The community is encouraged to assist in setting up testing environments for the beta content. For more information on the content contained in the repository, see the docs page. 2.1.1 Running CloudSlang Content The simplest way to get started running ready-made CloudSlang content is to download and run the pre-packaged cslang-cli-with-content file as described in the Get Started section. Alternatively, you can build the CLI from source and download the content separately. To build the CLI yourself and for more information on using the CLI, see the CLI section. Note: When using a locally built CLI you may need to include a classpath to properly reference ready-made content. For information on using classpaths, see Run with Dependencies. 2.1.2 Contributing Content We welcome and encourage community contributions to CloudSlang. Please see the contribution section to familiarize yourself with the Contribution Guidelines and Project Roadmap before contributing. 2.2 Hello World The following is a simple example to give you an idea of how CloudSlang is structured and can be used to ensure your environment is set up properly to run flows. 7 Test Documentation, Release 8 2.2.1 Prerequisites This example uses the CloudSlang CLI to run a flow. See the CloudSlang CLI section for instructions on how to download and run the CLI. Although CloudSlang files can be composed in any text editor, using a modern code editor with support for YAML syntax highlighting is recommended. See CloudSlang Editors for instructions on how to download, install and use the CloudSlang language package for Atom. 2.2.2 Code files In a new folder, create two new CloudSlang files, hello_world.sl and print.sl, and copy the code below. hello_world.sl namespace: examples.hello_world flow: name: hello_world workflow: - sayHi: do: print: - text:"Hello, World" print.sl namespace: examples.hello_world operation: name: print inputs: - text action: python_script: print text results: - SUCCESS 2.2.3 Run Start the CLI from the folder in which