← Back to branch summary

~ibmcharmers/charms/trusty/layer-ibm-mobilefirst-server/devel

« back to all changes in this revision

Viewing changes to deps/layer/layer-apt/README.md

  • Committer: Suchitra Venugopal
  • Date: 2016-09-06 09:48:53 UTC
  • Revision ID: suchvenu@in.ibm.com-20160906094853-1n09myeisek096nm
IBM MobileFirst Server

Show diffs side-by-side

added added

removed removed

Lines of Context:
deps/layer/layer-apt/README.md
 
1
# Apt layer
 
2
 
 
3
The Apt layer for Juju enables layered charms to more easily deal with
 
4
deb packages and apt sources in a simple and efficient manner. It
 
5
provides consistent configuration for operators, allowing them to
 
6
easily specify custom apt sources and additional debs required for
 
7
their particular installations.
 
8
 
 
9
## Configuration
 
10
 
 
11
The charm may provide defaults for these service configuration
 
12
(config.yaml) options, and the operator may override them as required.
 
13
 
 
14
* `extra_packages`
 
15
 
 
16
  A space separated list of additional deb packages to install on
 
17
  each unit.
 
18
 
 
19
* `package_status`
 
20
 
 
21
  'install' or 'hold'. When set to hold, packages installed using
 
22
  the Apt layer API will be pinned, so that they will not be
 
23
  automatically upgraded when package updates are performed. 'hold'
 
24
  is particularly useful for allowing a service such as Landscape
 
25
  to automatically apply security updates to most of the system,
 
26
  whilst holding back any potentially service affecting updates.
 
27
 
 
28
* `install_sources`
 
29
 
 
30
  A list of apt sources containing the packages that need to be installed.
 
31
  Each source may be either a line that can be added directly to
 
32
  sources.list(5), or in the form ppa:<user>/<ppa-name> for adding
 
33
  Personal Package Archives, or a distribution component to enable.
 
34
  The list is a yaml list, encoded as a string. The nicest way of
 
35
  declaring this in a yaml file looks like the following (in particular,
 
36
  the | character indicates that the value is a multiline string):
 
37
 
 
38
  ```yaml
 
39
  install_sources: |
 
40
      - ppa:stub/cassandra
 
41
      - deb http://www.apache.org/dist/cassandra/debian 21x main
 
42
  ```
 
43
 
 
44
* `install_keys`
 
45
 
 
46
  A list of GPG signing keys to accept. There needs to be one entry
 
47
  per entry in install_sources. null may be used if no keep is
 
48
  needed, which is the case for PPAs and for the standard Ubuntu
 
49
  archives. Keys should be full ASCII armoured GPG public keys.
 
50
  GPG key ids are also accepted, but in most environments this
 
51
  mechanism is not secure. The install_keys list, like
 
52
  install_sources, must also be a yaml formatted list encoded as
 
53
  a string:
 
54
 
 
55
  ```yaml
 
56
  install_keys: |
 
57
      - null
 
58
      - |
 
59
          -----BEGIN PGP PUBLIC KEY BLOCK-----
 
60
          Version: GnuPG v1
 
61
 
 
62
          mQINBFQJvgUBEAC0KcYCTj0hd15p4fiXBsbob0sKgsvN5Lm7N9jzJWlGshJ0peMi
 
63
          kH8YhDXw5Lh+mPEHksL7t1L8CIr1a+ntns/Opt65ZPO38ENVkOqEVAn9Z5sIoZsb
 
64
          AUeLlJzSeRLTKhcOugK7UcsQD2FHnMBJz50bxis9X7pjmnc/tWpjAGJfaWdjDIo=
 
65
          =yiQ4
 
66
          -----END PGP PUBLIC KEY BLOCK-----
 
67
  ```
 
68
 
 
69
## Usage
 
70
 
 
71
Queue packages for installation, and have handlers waiting for
 
72
these packages to finish being installed:
 
73
 
 
74
```python
 
75
import charms.apt
 
76
 
 
77
@hook('install')
 
78
def install():
 
79
    charms.apt.queue_install(['git'])
 
80
 
 
81
@when_not('apt.installed.gnupg')
 
82
def install_gnupg():
 
83
    charms.apt.queue_install(['gnupg'])
 
84
 
 
85
@when('apt.installed.git')
 
86
@when('apt.installed.gnupg')
 
87
def grabit():
 
88
    clone_repo()
 
89
    validate_repo()
 
90
```
 
91
 
 
92
### API
 
93
 
 
94
Several methods are exposed in the charms.apt Python package.
 
95
 
 
96
* `add_source(source, key=None)`
 
97
 
 
98
  Add an apt source.
 
99
 
 
100
  A source may be either a line that can be added directly to
 
101
  sources.list(5), or in the form ppa:<user>/<ppa-name> for adding
 
102
  Personal Package Archives, or a distribution component to enable.
 
103
 
 
104
  The package signing key should be an ASCII armoured GPG key. While
 
105
  GPG key ids are also supported, the retrieval mechanism is insecure.
 
106
  There is no need to specify the package signing key for PPAs or for
 
107
  the main Ubuntu archives.
 
108
 
 
109
  It is preferable if charms do not call this directly to hard
 
110
  coded apt sources, but instead have these sources listed
 
111
  as defaults in the install_sources config option. This allows
 
112
  operators to mirror your packages to internal archives and
 
113
  deploy your charm in environments without network access.
 
114
 
 
115
  Sets the `apt.needs_update` reactive state.
 
116
 
 
117
* `queue_install(packages, options=None)`
 
118
 
 
119
  Queue one or more deb packages for install. The actual package
 
120
  installation will be performed later by a handler in the
 
121
  apt layer. The `apt.installed.{name}` state will be set once
 
122
  the package installed (one state for each package).
 
123
 
 
124
  If a package has already been installed it will not be reinstalled.
 
125
 
 
126
  If a package has already been queued it will not be requeued, and
 
127
  the install options will not be changed.
 
128
 
 
129
* `installed()`
 
130
 
 
131
  Returns the set of deb packages installed by this layer.
 
132
 
 
133
* `purge(packages)`
 
134
 
 
135
  Purge one or more deb packages from the system
 
136
 
 
137
 
 
138
### Extras
 
139
 
 
140
These methods are called automatically by the reactive framework as
 
141
reactive state demands. However, you can also invoke them directly
 
142
if you want the operation done right now.
 
143
 
 
144
* `update()`
 
145
 
 
146
  Update the apt cache. Removes the `apt.needs_update` state.
 
147
 
 
148
 
 
149
* `install_queued()`
 
150
 
 
151
  Installs deb packages queued for installation. On success, removes
 
152
  the `apt.queued_installs` state, sets the `apt.installed.{packagename}`
 
153
  state for each installed package, and returns True. On failure,
 
154
  sets the unit workload status to blocked and returns False.
 
155
  The package installs remain queued.
 
156
 
 
157
 
 
158
## Support
 
159
 
 
160
This layer is maintained on Launchpad by
 
161
Stuart Bishop (stuart.bishop@canonical.com).
 
162
 
 
163
Code is available using git at git+ssh://git.launchpad.net/layer-apt.
 
164
 
 
165
Bug reports can be made at https://bugs.launchpad.net/layer-apt.
 
166
 
 
167
Queries and comments can be made on the Juju mailing list, Juju IRC
 
168
channels, or at https://answers.launchpad.net/layer-apt.