5093f3120e
This is a big commit, and I apologize in advance for the future
git-blames all pointing to me. This commit does a few things:
1. Merges the website/docs and website/www repo into a single website repo
to be in line with other HashiCorp projects
2. Updates to use middleman-hashicorp
3. Converts less to scss to be in line with other projects
4. Updates page styles to be in line with other projects
5. Optimizes images
6. Prepare for S3 + Fastly deployment with scripts, etc.
7. Removes blog posts (they have been transferred to hashicorp.com with
redirects in place
8. Updated sitemap generation script for better SEO
9. Fixed many broken links
10. Add description to all fields
105 lines
3.8 KiB
Markdown
105 lines
3.8 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Guest Capabilities - Plugin Development"
|
|
sidebar_current: "plugins-guestcapabilities"
|
|
description: |-
|
|
This page documents how to add new capabilities for guests to Vagrant,
|
|
allowing Vagrant to perform new actions on specific guest operating systems.
|
|
Prior to reading this, you should be familiar with the plugin development
|
|
basics.
|
|
---
|
|
|
|
# Plugin Development: Guest Capabilities
|
|
|
|
This page documents how to add new capabilities for [guests](/docs/plugins/guests.html)
|
|
to Vagrant, allowing Vagrant to perform new actions on specific guest
|
|
operating systems.
|
|
Prior to reading this, you should be familiar
|
|
with the [plugin development basics](/docs/plugins/development-basics.html).
|
|
|
|
<div class="alert alert-warning">
|
|
<strong>Warning: Advanced Topic!</strong> Developing plugins is an
|
|
advanced topic that only experienced Vagrant users who are reasonably
|
|
comfortable with Ruby should approach.
|
|
</div>
|
|
|
|
Guest capabilities augment [guests](/docs/plugins/guests.html) by attaching
|
|
specific "capabilities" to the guest, which are actions that can be performed
|
|
in the context of that guest operating system.
|
|
|
|
The power of capabilities is that plugins can add new capabilities to
|
|
existing guest operating systems without modifying the core of Vagrant.
|
|
In earlier versions of Vagrant, all the guest logic was contained in the
|
|
core of Vagrant and was not easily augmented.
|
|
|
|
## Definition Component
|
|
|
|
Within the context of a plugin definition, guest capabilities can be
|
|
defined like so:
|
|
|
|
```ruby
|
|
guest_capability "ubuntu", "my_custom_capability" do
|
|
require_relative "cap/my_custom_capability"
|
|
Cap::MyCustomCapability
|
|
end
|
|
```
|
|
|
|
Guest capabilities are defined by calling the `guest_capability` method,
|
|
which takes two parameters: the guest to add the capability to, and the
|
|
name of the capability itself. Then, the block argument returns a class
|
|
that implements a method named the same as the capability. This is
|
|
covered in more detail in the next section.
|
|
|
|
## Implementation
|
|
|
|
Implementations should be classes or modules that have a method with
|
|
the same name as the capability. The method must be immediately accessible
|
|
on the class returned from the `guest_capability` component, meaning that
|
|
if it is an instance method, an instance should be returned.
|
|
|
|
In general, class methods are used for capabilities. For example, here
|
|
is the implementation for the capability above:
|
|
|
|
```ruby
|
|
module Cap
|
|
class MyCustomCapability
|
|
def self.my_custom_capability(machine)
|
|
# implementation
|
|
end
|
|
end
|
|
end
|
|
```
|
|
|
|
All capabilities get the Vagrant machine object as the first argument.
|
|
Additional arguments are determined by the specific capability, so view the
|
|
documentation or usage of the capability you are trying to implement for more
|
|
information.
|
|
|
|
Some capabilities must also return values back to the caller, so be aware
|
|
of that when implementing a capability.
|
|
|
|
Capabilities always have access to communication channels such as SSH
|
|
on the machine, and the machine can generally be assumed to be booted.
|
|
|
|
## Calling Capabilities
|
|
|
|
Since you have access to the machine in every capability, capabilities can
|
|
also call _other_ capabilities. This is useful for using the inheritance
|
|
mechanism of capabilities to potentially ask helpers for more information.
|
|
For example, the "redhat" guest has a "network\_scripts\_dir" capability that
|
|
simply returns the directory where networking scripts go.
|
|
|
|
Capabilities on child guests of RedHat such as CentOS or Fedora use this
|
|
capability to determine where networking scripts go, while sometimes overriding
|
|
it themselves.
|
|
|
|
Capabilities can be called like so:
|
|
|
|
```ruby
|
|
machine.guest.capability(:capability_name)
|
|
```
|
|
|
|
Any additional arguments given to the method will be passed on to the
|
|
capability, and the capability will return the value that the actual
|
|
capability returned.
|