imjasonh/gcloud-help
1
0
Fork 0
mirror of https://github.com/imjasonh/gcloud-help synced 2026-07-15 01:15:34 +00:00
Code Activity
gcloud-help/gcloud/beta/compute/instances/ops-agents/policies/create
Automated ec6dc40f99 gcloud: Wed Dec 11 10:18:23 UTC 2024
2024-12-11 10:18:23 +00:00

353 lines
16 KiB
Text
Raw Blame History

NAME
gcloud beta compute instances ops-agents policies create - create a Google
Cloud's operations suite agents (Ops Agents) policy
SYNOPSIS
gcloud beta compute instances ops-agents policies create POLICY_ID
--agent-rules=type=TYPE,version=VERSION,package-state=PACKAGE-STATE,
enable-autoupgrade=ENABLE-AUTOUPGRADE;[...]
--os-types=short-name=SHORT-NAME,version=VERSION;[...]
[--description=DESCRIPTION]
[--group-labels=[LABEL_NAME=LABEL_VALUE,
LABEL_NAME=LABEL_VALUE,...;...]]
[--instances=[zones/ZONE_NAME/instances/INSTANCE_NAME,...]]
[--zones=[ZONE_NAME,...]] [GCLOUD_WIDE_FLAG ...]
DESCRIPTION
(BETA) gcloud beta compute instances ops-agents policies create creates a
policy that facilitates agent management across Compute Engine instances
based on user specified instance filters. This policy installs, specifies
versioning, enables autoupgrade, and removes Ops Agents.
The command returns the content of the created policy or an error
indicating why the creation fails. The created policy takes effect
asynchronously. It can take 10-15 minutes for the VMs to enforce the newly
created policy.
EXAMPLES
To create a policy named ops-agents-test-policy that targets a single
CentOS 7 VM instance named zones/us-central1-a/instances/test-instance for
testing or development and installs both Logging and Monitoring Agents on
that VM instance, run:
$ gcloud beta compute instances ops-agents policies create \
ops-agents-test-policy \
--agent-rules="type=logging,enable-autoupgrade=false;type=metric\
s,enable-autoupgrade=false" --description="A test policy." \
--os-types=short-name=centos,version=7 \
--instances=zones/us-central1-a/instances/test-instance
To create a policy named ops-agents-prod-policy that targets all CentOS 7
VMs in zone us-central1-a with either env=prod,product=myapp or
env=staging,product=myapp labels and makes sure the logging agent and
metrics agent versions are pinned to specific major versions for staging
and production, run:
$ gcloud beta compute instances ops-agents policies create \
ops-agents-prod-policy \
--agent-rules="type=logging,version=1.*.*,enable-autoupgrade=fal\
se;type=metrics,version=6.*.*,enable-autoupgrade=false" \
--description="A prod policy." \
--os-types=short-name=centos,version=7 --zones=us-central1-a \
--group-labels="env=prod,product=myapp;env=staging,product=myapp\
"
To create a policy named ops-agents-prod-policy that targets all CentOS 7
VMs in zone us-central1-a with either env=prod,product=myapp or
env=staging,product=myapp labels and makes sure the ops-agent version is
pinned to specific major versions for staging and production, run:
$ gcloud beta compute instances ops-agents policies create \
ops-agents-prod-policy \
--agent-rules="type=ops-agent,version=1.*.*,enable-autoupgrade=f\
alse" --description="A prod policy." \
--os-types=short-name=centos,version=7 --zones=us-central1-a \
--group-labels="env=prod,product=myapp;env=staging,product=myapp\
"
POSITIONAL ARGUMENTS
POLICY_ID
ID of the policy.
This ID must start with ops-agents-, contain only lowercase letters,
numbers, and hyphens, end with a number or a letter, be between 1-63
characters, and be unique within the project. The goal of the prefix
ops-agents- is to easily distinguish these Ops Agents specific policies
from other generic policies and lower the chance of naming conflicts.
REQUIRED FLAGS
--agent-rules=type=TYPE,version=VERSION,package-state=PACKAGE-STATE,enable-autoupgrade=ENABLE-AUTOUPGRADE;[...]
A non-empty list of agent rules to be enforced by the policy.
This flag must be quoted. Items in the list are separated by ";". Each
item in the list is a <key, value> map that represents a logging or
metrics agent. The allowed values of the key are as follows.
type
Type of agent to manage.
Required. Allowed values: logging, metrics and ops-agent. Use
logging for the Logging Agent
(https://cloud.google.com/logging/docs/agent). Use metrics for the
Monitoring Agent (https://cloud.google.com/monitoring/agent). Use
ops-agent for the Ops Agent
(https://cloud.google.com/stackdriver/docs/solutions/ops-agent).
The Ops Agent has both a logging module and a metrics module
already. So other types of agents are not allowed when there is an
agent with type ops-agent. See
https://cloud.google.com/stackdriver/docs/solutions/agents#which-agent-should-you-choose
for which agent to use.
enable-autoupgrade
Whether to enable autoupgrade of the agent.
Required. Allowed values: true or false. This has to be false if
the agent version is set to a specific patch version in the format
of version=MAJOR_VERSION.MINOR_VERSION.PATCH_VERSION.
version
Version of the agent to install.
Optional. Default to version=current-major. The allowed values and
formats are as follows.
version=latest
With this setting, the latest version of the agent is installed
at the time when the policy is applied to an instance.
If multiple instances are created at different times but they
all fall into the instance filter rules of an existing policy,
they may end up with different versions of the agent, depending
on what the latest version of the agent is at the policy
application time (in this case the instance creation time). One
way to avoid this is to set enable-autoupgrade=true. This
guarantees that the installed agents on all instances that are
managed by this policy are always up to date and conform to the
same version.
While this version=latest setting makes it easier to keep the
agent version up to date, this setting does come with a
potential risk. When a new major version is released, the
policy may install the latest version of the agent from that
new major release, which may introduce breaking changes. For
production environments, consider using the
version=MAJOR_VERSION.*.* setting below for safer agent
deployments.
version=MAJOR_VERSION.*.*
With this setting, the latest version of agent from a specific
major version is installed at the time when the policy is
applied to an instance.
If multiple instances are created at different times but they
all fall into the instance filter rules of an existing policy,
they may end up with different versions of the agent, depending
on what the latest version of the agent is at the policy
application time (in this case the instance creation time). One
way to avoid this is to set enable-autoupgrade=true. This
guarantees that the installed agents on all instances that are
managed by this policy are always up to date within that major
version and conform to the same version.
When a new major release is out, this setting ensures that only
the latest version from the specified major version is
installed, which avoids accidentally introducing breaking
changes. This is recommended for production environments to
ensure safer agent deployments.
version=current-major
With this setting, the version field is automatically set to
version=MAJOR_VERSION.*.*, where MAJOR_VERSION is the current
latest major version released. Refer to the
version=MAJOR_VERSION.*.* section for the expected behavior.
version=MAJOR_VERSION.MINOR_VERSION.PATCH_VERSION
With this setting, the specified exact version of agent is
installed at the time when the policy is applied to an
instance. enable-autoupgrade must be false for this setting.
This setting is not recommended since it prevents the policy
from installing new versions of the agent that include bug
fixes and other improvements.
One limitation of this setting is that if the agent gets
manually uninstalled from the instances after the policy gets
applied, the policy can only ensure that the agent is
re-installed. It is not able to restore the expected exact
version of the agent.
version=5.5.2-BUILD_NUMBER
Allowed for the metrics agent (type=metrics) only.
With this setting, the specified exact build number of the
deprecated 5.5.2 metrics agent is installed at the time when
the policy is applied to an instance. enable-autoupgrade must
be false for this setting.
This setting is deprecated and will be decommissioned along
with the 5.5.2 metrics agent on Apr 28, 2021
(https://cloud.google.com/stackdriver/docs/deprecations/mon-agent).
It is not recommended since it prevents the policy from
installing new versions of the agent that include bug fixes and
other improvements.
One limitation of this setting is that if the agent gets
manually uninstalled from the instances after the policy gets
applied, the policy can only ensure that the agent is
re-installed. It is not able to restore the expected exact
version of the agent.
package-state
Desired package state of the agent.
Optional. Default to package-state=installed. The allowed values
are as follows.
package-state=installed
With this setting, the policy will ensure the agent package is
installed on the instances and the agent service is running.
package-state=removed
With this setting, the policy will ensure the agent package is
removed from the instances, which stops the service from
running.
--os-types=short-name=SHORT-NAME,version=VERSION;[...]
A non-empty list of OS types to filter instances that the policy
applies to.
For Alpha and Beta, exactly one OS type needs to be specified. The
support for multiple OS types will be added later for more flexibility.
Each OS type is defined by the combination of short-name and version
fields.
Sample values:
OS Short Name OS Version
centos 8
centos 7
debian 12
debian 11
debian 10
debian 9
rhel 9.*
rhel 8.*
rhel 7.*
rocky 9.*
rocky 8.*
sles 12.*
sles 15.*
sles_sap 12.*
sles_sap 15.*
ubuntu 16.04
ubuntu 18.04
ubuntu 19.10
ubuntu 20.04
ubuntu 21.04
ubuntu 21.10
ubuntu 22.04
ubuntu 23.04
ubuntu 23.10
ubuntu 24.04
ubuntu 24.10
windows 10.*
windows 6.*
short-name
Short name of the OS.
Required. Allowed values: centos, debian, rhel, rocky, sles,
sles_sap, ubuntu.
To inspect the exact OS short name of an instance, run:
$ gcloud beta compute instances os-inventory describe \
INSTANCE_NAME | grep "^ShortName: "
Under the hood, this value is derived from the ID field in the
/etc/os-release file for most operating systems.
version
Version of the OS.
Required. This can be either an exact match or a prefix followed by
the * wildcard.
To inspect the exact OS version of an instance, run:
$ gcloud beta compute instances os-inventory describe \
INSTANCE_NAME | grep "^Version: "
Under the hood, this value is derived from the VERSION_ID field in
the /etc/os-release file for most operating systems.
OPTIONAL FLAGS
--description=DESCRIPTION
Description of the policy.
--group-labels=[LABEL_NAME=LABEL_VALUE,LABEL_NAME=LABEL_VALUE,...;...]
A list of label maps to filter instances that the policy applies to.
Optional. The --group-labels flag needs to be quoted. Each label map
item in the list are separated by ;. To manage instance labels, refer
to:
$ gcloud beta compute instances add-labels
$ gcloud beta compute instances remove-labels
Each label map item in the --group-labels list is a map in the format
of LABEL_NAME=LABEL_VALUE,LABEL_NAME=LABEL_VALUE,.... An instance has
to match all of the LABEL_NAME=LABEL_VALUE criteria inside a label map
to be considered a match for that label map. But the instance only
needs to match one label map in the --group-labels list.
For example,
--group-labels="env=prod,product=myapp;env=staging,product=myapp"
implies the matching criteria is:
(env=prod AND product=myapp) OR (env=staging AND product=myapp)
--instances=[zones/ZONE_NAME/instances/INSTANCE_NAME,...]
A list of fully-qualified names to filter instances that the policy
applies to.
Each item in the list must be in the format of
zones/ZONE_NAME/instances/INSTANCE_NAME. The policy can also target
instances that are not yet created.
To list all existing instances, run:
$ gcloud compute instances list
The --instances flag is recommended for use during development and
testing. In production environments, it's more common to select
instances via a combination of --zones and --group-labels.
--zones=[ZONE_NAME,...]
A list of zones to filter instances to apply the policy.
To list available zones, run:
$ gcloud compute zones list
The use of the --zones and --group-labels flags is recommended for
production environments. For testing and development, it's more common
to select instances directly via the --instances flag.
GCLOUD WIDE FLAGS
These flags are available to all commands: --access-token-file, --account,
--billing-project, --configuration, --flags-file, --flatten, --format,
--help, --impersonate-service-account, --log-http, --project, --quiet,
--trace-token, --user-output-enabled, --verbosity.
Run $ gcloud help for details.
NOTES
This command is currently in beta and might change without notice. These
variants are also available:
$ gcloud compute instances ops-agents policies create
$ gcloud alpha compute instances ops-agents policies create
View git blame Copy permalink