mbrukman / puppetlabs-gce_compute Goto Github PK

  gce_instance { 'puppet-enterprise-master':
      ensure       => present,
      description  => 'A Puppet Enterprise Master and Console',
      machine_type => 'n1-standard-1',
      zone         => 'us-central1-a',
      network      => 'default',
      image        => 'projects/centos-cloud/global/images/centos-6-v20131120',
      tags         => ['puppet', 'pe-master'],
      startupscript        => 'puppet-enterprise.sh',
      metadata             => {
        'pe_role'          => 'master',
        'pe_version'       => '3.3.1',
        'pe_consoleadmin'  => '[email protected]',
        'pe_consolepwd'    => 'puppetize',
      },
      service_account_scopes => ['compute-ro'],
  }

  gce_instance { 'sample-agent':
    ensure         => present,
    zone           => 'us-central1-a',
    machine_type   => 'g1-small',
    network        => 'default',
    image          => 'projects/centos-cloud/global/images/centos-6-v20131120',
    startupscript  => 'pe-simplified-agent.sh',
    metadata       => {
      'pe_role'    => 'agent',
      'pe_master'  => 'puppet-enterprise-master',
      'pe_version' => '3.3.1',
    },
    tags           => ['puppet', 'pe-agent'],
  }
  ```

  ```
  puppet apply agent.pp
  ```

4. (Optionally) Use the future parser to build many more instances.

  ```puppet
  $a = ['1','2','3','4','5','6','7','8']
  each( $a ) |$value|{

    gce_instance { "sample-agent-${value}":
      ensure         => present,
      zone           => 'us-central1-a',
      machine_type   => 'g1-small',
      network        => 'default',
      image          => 'projects/centos-cloud/global/images/centos-6-v20131120',
      startupscript  => 'pe-simplified-agent.sh',
      metadata       => {
        'pe_role'    => 'agent',
        'pe_master'  => 'puppet-enterprise-master',
        'pe_version' => '3.3.1',
      },
      tags           => ['puppet', 'pe-agent'],
    }

  }
  ```

  ```
  puppet apply agent.pp --parser future
  ```

## A Complete Demo Stack

Google Cloud Platform hosts [a complete demo stack on GitHub](https://github.com/GoogleCloudPlatform/compute-video-demo-puppet). It includes more GCE resources like load balancers and firewall rules.

## Reference

The gce_compute module provides the following resource types:

* `gce_instance` - Virtual machine instances that can be assigned roles.
* `gce_disk`     - Persistent disks that can be attached to instances.
* `gce_firewall` - Firewall rules that specify the traffic to your instances.
* `gce_network`  - Networks that routes internal traffic between virtual machine
instances. Firewalls and instances are associated with networks.
* `gce_forwardingrule`  - Load balancer forwarding rules.
* `gce_httphealthcheck`  - Load balancer HTTP health checking.
* `gce_targetpool` - Load balancer collection of instances.
* `gce_targetpoolhealthcheck`  - Assignment of a health-check to a targetpool.
* `gce_targetpoolinstance`  - Assignment of an instance to a targetpool.

These types allow users to describe application stacks in Google Compute
Engine using Puppet's DSL. This provides the following benefits:

* Users can express application deployments as text that can be version
controlled.
* Teams can share and collaborate on application deployments described using
Puppet's DSL.
* Users can take advantage of the composition aspects of the Puppet DSL to
create reusable and extendable abstraction layers on top of multi-node
deployment descriptions.
* Allows Puppet to support ongoing management of application stacks created in
GCE.

#### Service Account Scopes

Note that if your GCE instances will need access to other Google Cloud
services (e.g.
[Google Cloud Storage](https://cloud.google.com/products/cloud-storage),
[Google BigQuery](https://cloud.google.com/products/big-query), etc.) then you
can specify access with the `--service_account_scopes`. For more information
about Service Account scopes, see
[this page](https://developers.google.com/compute/docs/authentication).

The PE Quick Start example assigns the Master a compute-ro service scope which
allows it to query metadata about other instances within the GCE project. This
information is used for automatic certificate signing.

#### Automatic Certificate Signing

If you plan to host your Puppet master and agents in Google Compute Engine, this
module can take advantage of Google's API and Metadata services to verify and
automatically connect agents to the master so that they can immediately be assigned
work after creation.

To use this capability, you must specify particular properties in your gce_instance resources.

- Within the Puppet Master resource, assign a service account scope that can query GCE metadata.

`service_account_scopes => ['compute-ro'],`

- The Puppet Master resource also needs to install the gce_compute module and configure itself with the provided autosigner class.

```puppet
  modules  => ['puppetlabs-gce_compute'],
  manifest => 'include gce_compute::autosign',
  ```

- Within the Puppet Agent resources, assign the `pe-simplified-agent.sh` startup script.

`startupscript  => 'pe-simplified-agent.sh',`

With this configuration, agents will retrieve particular metadata about themselves
from the GCE metadata service and insert them into their certificate signing request.
The Puppet Master will query the metadata service for the same information and ensure
that it matches what the agent claims in its CSR.

__Be careful.__ This configuration trusts that you've protected your Google credentials
and that you trust everyone who has credentials to provision instances inside of
your Google Compute Engine project. So long as this chain remains trustworthy, this
method will reliably connect newly provisioned instances to your PE infrastructure
without interaction.

#### Persistent Disks and Instances

When an instance is created, the module will first check to see if there is a
pre-existing persistent disk with the same name as the instance and attempt to
use that as the instance's boot disk. If no such disk exists, a new persistent
disk will be created.

When you delete an instance, the persistent disk will *not* be deleted. This
provides the default behavior of persisting your data between instance
termination and re-creation. If you truly want to delete a persistent disk,
you must do so explicitly with it's own type-block and `ensure => absent` attribute.

### Enable/Disable Live Instance Migration

Your Compute Engine instances, by default, will enable live migration.  In
the event that Google needs to perform a datacenter maintenance, your instance
will be automatically migrated to a new location without visible impact.
This feature can be disabled by setting `on_host_migration` to `false`.

### Classifying resources

`gce_instance` resources can also contain classification data to be used by the startup scripts described below.

The classification is currently only supported by running `puppet apply`
during the bootstrapping process of the created instances and can be done
with the `enc_classes` parameter that utilizes
[External Node Classifiers](http://docs.puppetlabs.com/guides/external_nodes.html)
or by passing in the contents of a manifest file with the `manifest` parameter.
If *both* parameters are specified, both will be applied to the instance with
ENC first followed by the manifest file.

Classification is specified with the following `gce_instance` parameters:

* `modules` - List of modules that should be installed from the
[forge](http://forge.puppetlabs.com/).

```puppet
  modules => ['puppetlabs-mysql', 'puppetlabs-apache']

   metadata             => {
	   'pe_role'          => 'master',
	   'pe_version'       => '3.1.0',
	   'pe_consoleadmin'  => '[email protected]',
	   'pe_consolepwd'    => 'puppetize',
   },

   metadata             => {
      'pe_role'          => 'agent',
      'pe_master'        => "[gce_instance_namevar].c.[gce_projectid].internal",
      'pe_version'       => '3.1.0',
   },

   startupscript => 'script_to_use.sh'
   startupscript => 'puppet-community.sh'
   startupscript => 'puppet-enterprise.sh'

    Gce_instance[database][internal_ip_address]

    # manifests/site.pp
    gce_disk { 'puppet-disk':
        ensure      => absent,
        zone        => 'us-central1-a',
    }
    gce_disk { 'www1':
        ensure      => absent,
        zone        => 'us-central1-a',
    }
    gce_disk { 'www2':
        ensure      => absent,
        zone        => 'us-central1-b',
    }
    gce_firewall { 'allow-http':
        ensure      => absent,
    }
    gce_instance { 'www1':
        ensure       => absent,
        zone         => 'us-central1-a',
    }
    gce_instance { 'www2':
        ensure       => absent,
        zone         => 'us-central1-b',
    }
    gce_httphealthcheck { 'basic-http':
        ensure       => absent,
    }
    gce_targetpool { 'www-pool':
        ensure       => absent,
        region       => 'us-central1',
    }
    gce_forwardingrule { 'www-rule':
        ensure       => absent,
        region       => 'us-central1',
    }

    Gce_instance["www1", "www2"] -> Gce_disk["www1", "www2", "puppet-disk"]
    Gce_forwardingrule["www-rule"] -> Gce_targetpool["www-pool"]
    Gce_targetpool["www-pool"] -> Gce_httphealthcheck["basic-http"]