Skip to content

Latest commit

 

History

History
121 lines (88 loc) · 4.36 KB

TUTORIAL.md

File metadata and controls

121 lines (88 loc) · 4.36 KB
Raw

Magic Modules Tutorial

Intro

This tutorial will walk you through the components that make up Magic Modules.

api.yaml

Each product's api definition is stored in the magic-modules repo.

Let's open .

Product Metadata

The provides metadata about the API, such as name, scopes, and versions.

Resources

Each api.yaml file contains a list of resources. A resource is an item in that product, such as a PubSub Topic, a Compute Instance, or a GKE Cluster. Let's the first one.

This section contains data about the resource, such as its name, description, and URLs.

Properties

Each resource contains a list of on the resource that a user might set when creating the resource, or access when reading it.

See the property type fields for more information about the values that can be set on properties.

[provider].yaml

Within each product directory, each provider has its own [provider].yaml file to set information specific to that provider.

Let's look at .

This file consists of information that is specific to Ansible, like Ansible version numbers, helper code, and additional files to include.

Making Changes

To add a new API or resource, the only files that need to be modified are api.yaml, each [provider].yaml, and any custom code or provider-specific extras.

Let's actually make a change. Go back to and change the description on the Topic resource.

Compiling magic-modules

Now, let's compile those changes.

Since we're running in Cloud Shell, this command will make sure we connect to GitHub via HTTPS instead of SSH. You will probably not have to do this in your typical development environment.

git config --file=.gitmodules submodule.build/ansible.url https://github.com/modular-magician/ansible.git && git submodule sync

Compiling magic-modules

Now, initialize the submodules in order to get an up-to-date version of each provider. Since we only changed the URL for Ansible, we'll only initialize that submodule.

git submodule update --init build/ansible

If you haven't already, run bundle install to make sure all ruby dependencies are available:

bundle install

Next, run the compiler:

bundle exec compiler -p products/pubsub -e ansible -o build/ansible

This command tells us to run the compiler for the pubsub API, and generate Ansible into the build/ansible directory (where the submodule is).

Let's see our changes! Navigate to the Ansible submodule and run git diff to see what changed:

cd build/ansible && git diff

Congratulations!

You've successfully made a change to a resource in Magic Modules.