From 7b6f4cb89b4d953f4abcdb1e62fcaf8349138349 Mon Sep 17 00:00:00 2001 From: Vincent Ambo Date: Sun, 17 Jun 2018 17:28:16 +0200 Subject: docs(README): Add non-GCP instructions to README --- README.md | 42 +++++++++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 9 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 0ed149fb8f..28b72b9872 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,20 @@ directly to a Google Compute Engine instance and will use the [metadata server][] to figure out credentials and instance identification. -## Usage +## Features + +* `journaldriver` persists the last forwarded position in the journal + and will resume forwarding at the same position after a restart +* `journaldriver` will recognise log entries in JSON format and + forward them appropriately to make structured log entries available + in Stackdriver +* `journaldriver` can be used outside of GCP by configuring static + credentials + +## Usage on Google Cloud Platform + +`journaldriver` does not require any configuration when running on GCP +instances. 1. Install `journaldriver` on the instance from which you wish to forward logs. @@ -26,19 +39,30 @@ identification. By default instances have the required permissions if Stackdriver Logging support is enabled in the project. -3. Start Stackdriver, for example via `systemd`. +3. Start `journaldriver`, for example via `systemd`. + + +## Usage outside of Google Cloud Platform + +When running outside of GCP, the following extra steps need to be +performed: + +1. Create a Google Cloud Platform service account with the "Log + Writer" role and download its private key in JSON-format. +2. When starting `journaldriver`, configure the following environment + variables: + + * `GOOGLE_CLOUD_PROJECT`: Name of the GCP project to which logs + should be written. + * `GOOGLE_APPLICATION_CREDENTIALS`: Filesystem path to the + JSON-file containing the service account's private key. + * `LOG_NAME`: Name of the target log stream in Stackdriver Logging. + This will be automatically created if it does not yet exist. ## Upcoming features: * `journaldriver` will be added to [nixpkgs][] with a complementary [NixOS][] module for easy configuration. -* `journaldriver` will persist the latest `journald` cursor position, - allowing log reads to resume from the same position where they - stopped after a restart -* `journaldriver` will attempt to figure out whether logs are in - JSON-format and use the coresponding `jsonPayload` field in - Stackdriver Logging to make structured logs easily accessible -* `journaldriver` will support deployments on non-GCP machines [Stackdriver Logging]: https://cloud.google.com/logging/ [metadata server]: https://cloud.google.com/compute/docs/storing-retrieving-metadata -- cgit 1.4.1