Resources

Resources are the infrastructure objects managed by Shoreline.

A Resource refers to a specific host, pod, or container throughout the Shoreline platform. It may also refer to a more distinct entity, such as a virtual machine or a database instance.

Resource types are platform and provider agnostic. So whether it's a fleet of pods and containers in Kubernetes, stand-alone hosts, or many virtual machines, Shoreline can control those Resources within AWS, GCP, or Azure.

Discovering Resources

Operators need to understand how a workload maps to underlying Resources.

The CLI contains a handful of Op commands to analyze and monitor your Resources.

  • hosts: List all hosts.
op>
hosts
 ID | TYPE | NAME                | REGION    | AZ
 1  | HOST | i-064246cabcbb73067 | us-east-1 | us-east-1b
 2  | HOST | i-0812b3fd801632ecc | us-east-1 | us-east-1b
 3  | HOST | i-0189e804e46578b34 | us-east-1 | us-east-1a
  • containers: List all containers.
op>
containers
 ID | TYPE      | NAME                                               | REGION    | AZ
 13 | CONTAINER | test10-cust.shoreline-2cscc.shoreline              | us-east-1 | us-east-1a
 14 | CONTAINER | monitoring.test10c-prometheus-0.prometheus-server  | us-east-1 | us-east-1a
 15 | CONTAINER | monitoring.test10c-node-exporter-w5r42.prometheus  | us-east-1 | us-east-1a
 16 | CONTAINER | kube-system.kube-proxy-6trzf.kube-proxy            | us-east-1 | us-east-1a
 17 | CONTAINER | kube-system.coredns-7d74b564bd-lv8nh.coredns       | us-east-1 | us-east-1a
  • pods: List all pods.
op>
pods
 ID | TYPE | NAME                                                  | REGION    | AZ
 4  | POD  | test10-cust.shoreline-2cscc                           | us-east-1 | us-east-1a
 5  | POD  | monitoring.test10c-prometheus-0                       | us-east-1 | us-east-1a
 6  | POD  | monitoring.test10c-node-exporter-w5r42                | us-east-1 | us-east-1a
 7  | POD  | kube-system.kube-proxy-6trzf                          | us-east-1 | us-east-1a
 8  | POD  | kube-system.coredns-7d74b564bd-lv8nh                  | us-east-1 | us-east-1a

To list all your Resources combine multiple Resource types with the union function.

op>
hosts union pods union containers
 ID | TYPE      | NAME                                 | REGION    | AZ
 1  | HOST      | i-064246cabcbb73067                  | us-east-1 | us-east-1b
 2  | HOST      | i-0812b3fd801632ecc                  | us-east-1 | us-east-1b
 4  | POD       | test10-cust.shoreline-2cscc          | us-east-1 | us-east-1a
 5  | POD       | monitoring.test10c-prometheus-0      | us-east-1 | us-east-1a
 13 | CONTAINER | test10-cust.shoreline-2cscc          | us-east-1 | us-east-1a

Resource Relationships

Resources are also aware of their relationships with other Resources.

By piping multiple Resource queries into one statement you can traverse your Resource hierarchies.

Use the hosts command and pipe the result to the .pods command to retrieve the Kubernetes pods that are scheduled to each host:
op>
hosts | .pods
 ID | TYPE | NAME                                                  | REGION    | AZ
 24 | POD  | test10-cust.shoreline-tm5lh                           | us-east-1 | us-east-1b
 26 | POD  | monitoring.test10c-prometheus-1                       | us-east-1 | us-east-1b
 28 | POD  | monitoring.test10c-node-exporter-j6d8r                | us-east-1 | us-east-1b
 30 | POD  | kube-system.kube-proxy-99c5p                          | us-east-1 | us-east-1b
 32 | POD  | kube-system.coredns-7d74b564bd-b849k                  | us-east-1 | us-east-1b
Taking that a step further, pipe the above result to the .containers command to retrieve all containers in each pod scheduled to each host:
op>
hosts | .pods | .containers
 ID | TYPE      | NAME                                                   | REGION    | AZ
 44 | CONTAINER | test10-cust.shoreline-tm5lh.shoreline                  | us-east-1 | us-east-1b
 46 | CONTAINER | monitoring.test10c-prometheus-1.prometheus-server      | us-east-1 | us-east-1b
 47 | CONTAINER | monitoring.test10c-node-exporter-j6d8r.prometheus-node | us-east-1 | us-east-1b
 48 | CONTAINER | kube-system.kube-proxy-99c5p.kube-proxy                | us-east-1 | us-east-1b
 49 | CONTAINER | kube-system.coredns-7d74b564bd-b849k.coredns           | us-east-1 | us-east-1b

Named Resource

Use the resource command to create named Resource queries, avoiding repetition by storing valid Resource query strings.

For example, we're creating a named resource query called app_containers here.

op>
resource app_containers = hosts | .pods | .containers
Created resource 'app_containers'.

The app_containers command is now shorthand for hosts | .pods | .containers and returns the same result:

op>
app_containers
 ID | TYPE      | NAME                                                   | REGION    | AZ
 44 | CONTAINER | test10-cust.shoreline-tm5lh.shoreline                  | us-east-1 | us-east-1b
 46 | CONTAINER | monitoring.test10c-prometheus-1.prometheus-server      | us-east-1 | us-east-1b
 47 | CONTAINER | monitoring.test10c-node-exporter-j6d8r.prometheus-node | us-east-1 | us-east-1b
 48 | CONTAINER | kube-system.kube-proxy-99c5p.kube-proxy                | us-east-1 | us-east-1b
 49 | CONTAINER | kube-system.coredns-7d74b564bd-b849k.coredns           | us-east-1 | us-east-1b

The resource command illustrates the real power of Op.  With Op, you can build up robust commands layer by layer.

Filtering Resources

Let's expand on the app_containers query created above in Resource Relationships. You can filter the returned resources in Op by either type or tag.

For example, to get all of our containers in us-east-1a Availability Zone (AZ) we would run the following:

op>
app_containers | az = "us-east-1a"
 ID | TYPE      | NAME                                                   | REGION    | AZ
 13 | CONTAINER | test10-cust.shoreline-2cscc.shoreline                  | us-east-1 | us-east-1a
 14 | CONTAINER | monitoring.test10c-prometheus-0.prometheus-server      | us-east-1 | us-east-1a
 15 | CONTAINER | monitoring.test10c-node-exporter-w5r42.prometheus-node | us-east-1 | us-east-1a
 16 | CONTAINER | kube-system.kube-proxy-6trzf.kube-proxy                | us-east-1 | us-east-1a
 17 | CONTAINER | kube-system.coredns-7d74b564bd-lv8nh.coredns           | us-east-1 | us-east-1a

Inverting the equality comparator allows you to find all containers outside of the us-east-1a AZ:

op>
app_containers | az != "us-east-1a"
 ID | TYPE      | NAME                                                   | REGION    | AZ
 44 | CONTAINER | test10-cust.shoreline-tm5lh.shoreline                  | us-east-1 | us-east-1b
 46 | CONTAINER | monitoring.test10c-prometheus-1.prometheus-server      | us-east-1 | us-east-1b
 47 | CONTAINER | monitoring.test10c-node-exporter-j6d8r.prometheus-node | us-east-1 | us-east-1b
 48 | CONTAINER | kube-system.kube-proxy-99c5p.kube-proxy                | us-east-1 | us-east-1b
 49 | CONTAINER | kube-system.coredns-7d74b564bd-b849k.coredns           | us-east-1 | us-east-1b

Combining multiple tag strings into an array acts as an "OR" operation. Below we're seeking all containers in either the us-east-1a or us-east-1b AZs:

op>
app_containers | az = ["us-east-1a", "us-east-1b"]
 ID | TYPE      | NAME                                                   | REGION    | AZ
 44 | CONTAINER | test10-cust.shoreline-tm5lh.shoreline                  | us-east-1 | us-east-1b
 46 | CONTAINER | monitoring.test10c-prometheus-1.prometheus-server      | us-east-1 | us-east-1b
 13 | CONTAINER | test10-cust.shoreline-2cscc.shoreline                  | us-east-1 | us-east-1a
 14 | CONTAINER | monitoring.test10c-prometheus-0.prometheus-server      | us-east-1 | us-east-1a
 15 | CONTAINER | monitoring.test10c-node-exporter-w5r42.prometheus-node | us-east-1 | us-east-1a

As discussed in Resource Relationships, your resources are aware of their relationships. Using that internal awareness with piped commands provides some powerful capabilities.

For example, you can use both type and tag filtering with the following series of commands to drill down through the data set one step at a time. Beginning at the highest level of host:

  • Find all pods within the hosts.
  • Reduce the pods to only those in AZ us-east-1a.
  • Find all containers within the pods.
  • Finally, of those filtered pods, find those with a container_name of shoreline.
op>
hosts | .pods | az = "us-east-1a" | .containers | container_name = "shoreline"
 ID | TYPE      | NAME                                  | REGION    | AZ
 13 | CONTAINER | test10-cust.shoreline-2cscc.shoreline | us-east-1 | us-east-1a

Regex Filters

Resource queries support advanced regex filtering with the =~ and !=~ operators.

Get container Resources whose name contains line:

op>
containers | name =~ "line"
 ID  | TYPE      | NAME                                 | REGION    | AZ
 16  | CONTAINER | test2-cust.shoreline-wzrch.shoreline | us-west-2 | us-west-2a
 34  | CONTAINER | test2-cust.shoreline-n9d9f.shoreline | us-west-2 | us-west-2c
 36  | CONTAINER | test2-cust.shoreline-g6vlz.shoreline | us-west-2 | us-west-2a
 47  | CONTAINER | test2-cust.shoreline-lznw7.shoreline | us-west-2 | us-west-2a
 59  | CONTAINER | test2-cust.shoreline-8275f.shoreline | us-west-2 | us-west-2a

Get containers whose name does not contain line:

op>
containers | name !=~ "line"
 ID  | TYPE      | NAME                                    | REGION    | AZ
 17  | CONTAINER | monitoring.test2c-node-exporter-5bzpm   | us-west-2 | us-west-2a
 18  | CONTAINER | kube-system.kube-proxy-pblw7.kube-proxy | us-west-2 | us-west-2a
 19  | CONTAINER | kube-system.fluentd-gqnvp.fluentd       | us-west-2 | us-west-2a
 20  | CONTAINER | kube-system.aws-node-n8t5r.aws-node     | us-west-2 | us-west-2a
 38  | CONTAINER | monitoring.test2c-node-exporter-f2jkw   | us-west-2 | us-west-2c

You can also pass an array of strings that combines the results of filtering on each comparison value.

Get containers whose name contains either line or book:

op>
containers | name =~ ["line", "book"]
 ID  | TYPE      | NAME                                                     | REGION    | AZ
 47  | CONTAINER | test2-cust.shoreline-lznw7.shoreline                     | us-west-2 | us-west-2a
 59  | CONTAINER | test2-cust.shoreline-8275f.shoreline                     | us-west-2 | us-west-2a
 72  | CONTAINER | bookstore.bookstore-5c7cdd4956-58fcs.istio-proxy         | us-west-2 | us-west-2a
 76  | CONTAINER | test2-cust.shoreline-l72tz.shoreline                     | us-west-2 | us-west-2b
 77  | CONTAINER | bookstore.bookstore-5c7cdd4956-58fcs.bookstore-container | us-west-2 | us-west-2a

Get containers whose name does not contain either line or book:

op>
containers | name !=~ ["line", "book"]
  ID  | TYPE      | NAME                                             | REGION    | AZ
  17  | CONTAINER | monitoring.test2c-node-exporter-5bzpm.prometheus | us-west-2 | us-west-2a
  18  | CONTAINER | kube-system.kube-proxy-pblw7.kube-proxy          | us-west-2 | us-west-2a
  19  | CONTAINER | kube-system.fluentd-gqnvp.fluentd                | us-west-2 | us-west-2a
  20  | CONTAINER | kube-system.aws-node-n8t5r.aws-node              | us-west-2 | us-west-2a
  38  | CONTAINER | monitoring.test2c-node-exporter-f2jkw.prometheus | us-west-2 | us-west-2c

The Op Language is capable of many more powerful capabilities beyond this brief overview of Resources. Check out the Op Overview, Op Commands, and pre-built Op Packs.

Optional Parameters

Transform the results of a Resource query using these optional piped parameters.

base, offset

Get Resources that existed around the base Unix time, in milliseconds.

For example, return the number of containers that existed between July 13th, 2021 12:00:00 PM and July 13th, 2021 1:00:00 PM (UTC):

op>
hosts | .pods | .containers | base=1626177600000 | offset=3600000 | count
 RESOURCE_COUNT
 26

In the above we've set the base timestamp to July 13th, 2021 12:00:00 PM (UTC) and offset it by adding one hour.

You can also set a negative offset value to create a timestamp range starting before the base value:

op>
hosts | .pods | .containers | base=1626177600000 | offset=-3600000 | count
 RESOURCE_COUNT
 42

limit

The limit parameter restricts the number of returned Resources.

For example, here we're getting all 26 container Resources:

op>
hosts | .pods | .containers | count
 RESOURCE_COUNT
 26

Using limit we can reduce the number of Resources to 5:

op>
hosts | .pods | .containers | limit=5 | count
 RESOURCE_COUNT
 5

from, to

Get Resources that existed between the specified timespan, in milliseconds, since the Unix epoch.

For example, return the number of containers during the 24-hour period of July 13th, 2021 (UTC):

op>
hosts | .pods | .containers | from=1626134400000 | to=1626220800000 | count
 RESOURCE_COUNT
 26

Get containers between 5:00 and 6:00 PM on July 13th, 2021 (UTC):

op>
hosts | .pods | .containers | from=1626195600000 | to=1626199200000 | count
 RESOURCE_COUNT
 9

random

Randomly shuffles the order of the returned Resources.

By default, random is disabled.

op>
hosts | .pods | .containers | limit=5
 ID  | TYPE      | NAME                                                           | REGION    | AZ
 99  | CONTAINER | monitoring.test6c-node-exporter-6bv8c.prometheus-node-exporter | us-west-2 | us-west-2b
 100 | CONTAINER | kube-system.fluentd-lrzcq.fluentd                              | us-west-2 | us-west-2b
 101 | CONTAINER | test6-cust.shoreline-6md4h.shoreline                           | us-west-2 | us-west-2b
 102 | CONTAINER | kube-system.aws-node-w9bzb.aws-node                            | us-west-2 | us-west-2b
 103 | CONTAINER | kube-system.kube-proxy-bmbn5.kube-proxy                        | us-west-2 | us-west-2b

The above is equivalent to setting random to 0.

op>
hosts | .pods | .containers | random=0 | limit=5
 ID  | TYPE      | NAME                                                           | REGION    | AZ
 99  | CONTAINER | monitoring.test6c-node-exporter-6bv8c.prometheus-node-exporter | us-west-2 | us-west-2b
 100 | CONTAINER | kube-system.fluentd-lrzcq.fluentd                              | us-west-2 | us-west-2b
 101 | CONTAINER | test6-cust.shoreline-6md4h.shoreline                           | us-west-2 | us-west-2b
 102 | CONTAINER | kube-system.aws-node-w9bzb.aws-node                            | us-west-2 | us-west-2b
 103 | CONTAINER | kube-system.kube-proxy-bmbn5.kube-proxy                        | us-west-2 | us-west-2b

However, enabling random by setting it to 1 randomly shuffles the returned Resource collection.

op>
hosts | .pods | .containers | random=1 | limit=5
 ID  | TYPE      | NAME                                             | REGION    | AZ
 139 | CONTAINER | monitoring.test6c-prometheus-0.prometheus-server | us-west-2 | us-west-2c
 131 | CONTAINER | kube-system.aws-node-9rhtf.aws-node              | us-west-2 | us-west-2c
 134 | CONTAINER | ground.background-job-9nmb4.background-job       | us-west-2 | us-west-2c
 21  | CONTAINER | monitoring.test6c-prometheus-1.prometheus-server | us-west-2 | us-west-2a
 101 | CONTAINER | test6-cust.shoreline-6md4h.shoreline             | us-west-2 | us-west-2b

type

Restricts the Resources by type. Available values are:

  • HOST
  • POD
  • CONTAINER

For example, you can get all pod Resources within your hosts by specifying type="POD".

op>
hosts | type="POD" | count
 RESOURCE_COUNT
 26
op>
hosts | type="CONTAINER" | count
 RESOURCE_COUNT
 26