Merge branch 'master' into feature/personality

.github/.golangci.yml

@@ -0,0 +1,14 @@
+linters:
+  disable-all: true
+  enable:
+    - gci
+linters-settings:
+  gci:
+    sections:
+      - standard
+      - default
+      - Prefix(github.com/canonical/pebble)
+issues:
+  # these values ensure that all issues will be surfaced
+  max-issues-per-linter: 0
+  max-same-issues: 0

.github/.trivyignore

@@ -0,0 +1,6 @@
+# ignore known CVEs that are not backported before Go 1.17
+
+CVE-2022-41721
+CVE-2022-41717
+CVE-2022-41723
+CVE-2022-32149

.github/trivy.yaml

@@ -0,0 +1,4 @@
+timeout: 20m
+scan:
+  offline-scan: true
+ignore-file: .github/.trivyignore

.github/workflows/binaries.yml

@@ -27,7 +27,7 @@ jobs:
     - name: Set up Go
       uses: actions/setup-go@v4
       with:
-        go-version: stable  # latest stable version of Go
+        go-version-file: "go.mod"
 
     - name: Build binary and create archive
       id: build

.github/workflows/lint.yml

@@ -0,0 +1,30 @@
+name: Lint
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-go@v4
+        with:
+          go-mod-file: 'go.mod'
+          cache: false
+
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v3
+        id: lint
+        with:
+          version: latest
+          args: '-c .github/.golangci.yml --out-format=colored-line-number'
+          skip-cache: true
+
+      - name: Print error message
+        if: always() && steps.lint.outcome == 'failure'
+        run: |
+          echo '
+          Linting failed. On your local machine, please run
+              golangci-lint run -c .github/.golangci.yml --fix
+          and check in the changes.'
+          exit 1

.github/workflows/scanning.yml

@@ -0,0 +1,22 @@
+name: Vulnerability scanning
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  scan:
+    name: Scan for known vulnerabilities
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Run Github Trivy FS Action
+        uses: aquasecurity/trivy-action@master
+        with:
+          scan-type: 'fs'
+          scan-ref: '.'
+          trivy-config: .github/trivy.yaml

.github/workflows/snap.yml

@@ -0,0 +1,100 @@
+name: Pebble snap
+
+on:
+  pull_request:
+    branches: [master]
+  release:
+    types: [published]
+
+env:
+  SNAP_NAME: pebble
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      pebble-snap: ${{ steps.build-pebble-snap.outputs.snap }}
+
+    steps:
+      - name: Checkout Pebble repo
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+
+      - name: Build Pebble Snap
+        id: build-pebble-snap
+        uses: snapcore/action-build@v1
+
+      - name: Attach pebble snap to GH workflow execution
+        uses: actions/upload-artifact@v2
+        with:
+          name: ${{ steps.build-pebble-snap.outputs.snap }}
+          path: ${{ steps.build-pebble-snap.outputs.snap }}
+
+  test:
+    runs-on: ubuntu-latest
+    needs: [build]
+    outputs:
+      pebble-version: ${{ steps.install-pebble.outputs.version }}
+
+    steps:
+      - uses: actions/download-artifact@v3
+        with:
+          name: ${{ needs.build.outputs.pebble-snap }}
+
+      - name: Install the Pebble snap
+        id: install-pebble
+        run: |
+          set -ex
+          # Install the Pebble snap from the artifact built in the previous job
+          sudo snap install --dangerous --classic ${{ needs.build.outputs.pebble-snap }}
+
+          # Make sure Pebble is installed
+          echo "version=$(pebble version --client)" >> "$GITHUB_OUTPUT"
+
+      - name: Run smoke test
+        run: pebble enter --create-dirs exec echo Hello | grep Hello
+
+  promote:
+    if: ${{ github.event_name == 'release' }}
+    runs-on: ubuntu-latest
+    needs: [test]
+    strategy:
+      fail-fast: false
+      matrix:
+        arch: [amd64, arm64, ppc64el, armhf, s390x]
+    env:
+      TRACK: latest
+      DEFAULT_RISK: edge
+      TO_RISK: candidate
+    steps:
+      - name: Install Snapcraft
+        run: sudo snap install snapcraft --classic
+
+      - name: Wait for ${{ needs.test.outputs.pebble-version }} to be released
+        env:
+          SNAPCRAFT_STORE_CREDENTIALS: ${{ secrets.SNAPCRAFT_STORE_CREDENTIALS }}
+        run: |
+          while ! `snapcraft status ${{ env.SNAP_NAME }} --track ${{ env.TRACK }} --arch ${{ matrix.arch }} \
+              | grep "${{ env.DEFAULT_RISK }}" \
+              | awk -F' ' '{print $2}' \
+              | grep -Fxq "${{ needs.test.outputs.pebble-version }}"`; do
+            echo "[${{ matrix.arch }}] Waiting for ${{ needs.test.outputs.pebble-version }} \
+          to be released to ${{ env.TRACK }}/${{ env.DEFAULT_RISK }}..."
+            sleep 10
+          done
+
+      # It would be easier to use `snapcraft promote`, but there's an error when trying
+      # to avoid the prompt with the "--yes" option: 
+      # > 'latest/edge' is not a valid set value for --from-channel when using --yes.
+      - name: Promote ${{ needs.test.outputs.pebble-version }} (${{ matrix.arch }}) to ${{ env.TO_RISK }}
+        env:
+          SNAPCRAFT_STORE_CREDENTIALS: ${{ secrets.SNAPCRAFT_STORE_CREDENTIALS }}
+        run: |
+          revision="$(snapcraft status ${{ env.SNAP_NAME }} \
+            --track ${{ env.TRACK }} --arch ${{ matrix.arch }} \
+            | grep "${{ env.DEFAULT_RISK }}" | awk -F' ' '{print $3}')"
+
+          snapcraft release ${{ env.SNAP_NAME }} \
+            $revision \
+            ${{ env.TRACK }}/${{ env.TO_RISK }}

.github/workflows/tests.yml

@@ -13,15 +13,14 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        go: ['1.19', '1.18', '1.17', '1.16', '1.15', '1.14']
+        go: ['1.20']
 
     name: Go ${{ matrix.go }}
-
     steps:
     - uses: actions/checkout@v3
 
     - name: Set up Go
-      uses: actions/setup-go@v3
+      uses: actions/setup-go@v4
       with:
         go-version: ${{ matrix.go }}
 
@@ -34,14 +33,13 @@ jobs:
     runs-on: ubuntu-latest
 
     name: Root Tests
-
     steps:
     - uses: actions/checkout@v3
 
     - name: Set up Go
-      uses: actions/setup-go@v3
+      uses: actions/setup-go@v4
       with:
-        go-version-file: 'go.mod'
+        go-version: ${{ matrix.go }}
 
     - name: Test
       run: |
@@ -57,12 +55,11 @@ jobs:
     runs-on: ubuntu-latest
 
     name: Format check
-
     steps:
     - uses: actions/checkout@v3
 
     - name: Set up Go
-      uses: actions/setup-go@v3
+      uses: actions/setup-go@v4
       with:
         go-version-file: 'go.mod'
 

HACKING.md

@@ -83,6 +83,39 @@ $ curl --unix-socket ~/pebble/.pebble.socket 'http://localhost/v1/services?names
 ```
 
 
+## Code style
+
+Pebble imports should be arranged in three groups:
+- standard library imports
+- third-party / non-Pebble imports
+- Pebble imports (i.e. those prefixed with `github.com/canonical/pebble`)
+
+Imports should be sorted alphabetically within each group.
+
+We use the [`gopkg.in/check.v1`](https://pkg.go.dev/gopkg.in/check.v1) package for testing. Inside a test file, import this as follows:
+```go
+. "gopkg.in/check.v1"
+```
+so that identifiers from that package will be added to the local namespace.
+
+
+Here is an example of correctly arranged imports:
+
+```go
+import (
+	"fmt"
+	"net"
+	"os"
+
+	"github.com/gorilla/mux"
+	. "gopkg.in/check.v1"
+
+	"github.com/canonical/pebble/internals/systemd"
+	"github.com/canonical/pebble/internals/testutil"
+)
+```
+
+
 ## Running the tests
 
 Pebble has a suite of Go unit tests, which you can run using the regular `go test` command. To test all packages in the Pebble repository:

README.md

@@ -403,6 +403,60 @@ $ pebble run --verbose
 ...
 ```
 
+<!--
+TODO: uncomment this section once log forwarding is fully implemented
+TODO: add log targets to the Pebble layer spec below
+
+#### Log forwarding
+
+Pebble supports forwarding its services' logs to a remote Loki server or syslog receiver (via UDP/TCP). In the `log-targets` section of the plan, you can specify destinations for log forwarding, for example:
+```yaml
+log-targets:
+    loki-example:
+        override: merge
+        type: loki
+        location: http://10.1.77.205:3100/loki/api/v1/push
+        services: [all]
+    syslog-example:
+        override: merge
+        type: syslog
+        location: tcp://192.168.10.241:1514
+        services: [svc1, svc2]
+```
+
+For each log target, use the `services` key to specify a list of services to collect logs from. In the above example, the `syslog-example` target will collect logs from `svc1` and `svc2`.
+
+Use the special keyword `all` to match all services, including services that might be added in future layers. In the above example, `loki-example` will collect logs from all services.
+
+To remove a service from a log target when merging, prefix the service name with a minus `-`. For example, if we have a base layer with
+```yaml
+my-target:
+    services: [svc1, svc2]
+```
+and override layer with
+```yaml
+my-target:
+    services: [-svc1]
+    override: merge
+```
+then in the merged layer, the `services` list will be merged to `[svc1, svc2, -svc1]`, which evaluates left to right as simply `[svc2]`. So `my-target` will collect logs from only `svc2`.
+
+You can also use `-all` to remove all services from the list. For example, adding an override layer with
+```yaml
+my-target:
+    services: [-all]
+    override: merge
+```
+would remove all services from `my-target`, effectively disabling `my-target`. Meanwhile, adding an override layer with
+```yaml
+my-target:
+    services: [-all, svc1]
+    override: merge
+```
+would remove all services and then add `svc1`, so `my-target` would receive logs from only `svc1`.
+
+-->
+
 ## Container usage
 
 Pebble works well as a local service manager, but if running Pebble in a separate container, you can use the exec and file management APIs to coordinate with the remote system over the shared unix socket.
@@ -523,6 +577,10 @@ services:
         # group and group-id are specified, the group's GID must match group-id.
         group-id: <gid>
 
+        # (Optional) Working directory to run command in. By default, the
+        # command is run in the service manager's current directory.
+        working-dir: <directory>
+
         # (Optional) Defines what happens when the service exits with a zero
         # exit code. Possible values are: "restart" (default) which restarts
         # the service after the backoff delay, "shutdown" which shuts down and
@@ -630,6 +688,13 @@ checks:
             # directly, not interpreted by a shell.
             command: <commmand>
 
+            # (Optional) Run the command in the context of this service.
+            # Specifically, inherit its environment variables, user/group
+            # settings, and working directory. The check's context (the
+            # settings below) will override the service's; the check's
+            # environment map will be merged on top of the service's.
+            service-context: <service-name>
+
             # (Optional) A list of key/value pairs defining environment
             # variables that should be set when running the command.
             environment:
@@ -653,7 +718,8 @@ checks:
             # match group-id.
             group-id: <gid>
 
-            # (Optional) Working directory to run command in.
+            # (Optional) Working directory to run command in. By default, the
+            # command is run in the service manager's current directory.
             working-dir: <directory>
 ```
 
@@ -667,7 +733,7 @@ The Go client is used primarily by the CLI, but is importable and can be used by
 
 We try to never change the underlying HTTP API in a backwards-incompatible way, however, in rare cases we may change the Go client in a backwards-incompatible way.
 
-In addition to the Go client, there's also a [Python client](https://github.com/canonical/operator/blob/master/ops/pebble.py) for the Pebble API that's part of the Python Operator Framework used by Juju charms ([documentation here](https://juju.is/docs/sdk/interact-with-pebble)).
+In addition to the Go client, there's also a [Python client](https://github.com/canonical/operator/blob/master/ops/pebble.py) for the Pebble API that's part of the [`ops` library](https://github.com/canonical/operator) used by Juju charms ([documentation here](https://juju.is/docs/sdk/interact-with-pebble)).
 
 ## Roadmap / TODO