From cbb6dc92976c82a2bd86231e89420e3bd96c2055 Mon Sep 17 00:00:00 2001 From: tan Date: Fri, 6 Oct 2023 11:02:08 +0530 Subject: [PATCH 1/2] add initial docs Add initial docs, update README --- Project.toml | 2 +- README.md | 87 ++--------------------------- docs/.gitignore | 1 + docs/Manifest.toml | 119 ++++++++++++++++++++++++++++++++++++++++ docs/Project.toml | 5 ++ docs/make.jl | 23 ++++++++ docs/src/client.md | 25 +++++++++ docs/src/commandline.md | 42 ++++++++++++++ docs/src/index.md | 7 +++ docs/src/server.md | 20 +++++++ 10 files changed, 248 insertions(+), 83 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/Manifest.toml create mode 100644 docs/Project.toml create mode 100644 docs/make.jl create mode 100644 docs/src/client.md create mode 100644 docs/src/commandline.md create mode 100644 docs/src/index.md create mode 100644 docs/src/server.md diff --git a/Project.toml b/Project.toml index 40c5442..097036d 100644 --- a/Project.toml +++ b/Project.toml @@ -1,6 +1,6 @@ name = "OpenPolicyAgent" uuid = "8f257efb-743c-4ebc-8197-d291a1f743b4" -authors = ["Tanmay Mohapatra "] +authors = ["JuliaHub Inc.", "Tanmay Mohapatra "] version = "0.1.0" [deps] diff --git a/README.md b/README.md index 6f60a49..126e8ae 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,10 @@ # OpenPolicyAgent.jl -# OPA Command Line +[![Build Status](https://github.com/JuliaComputing/OpenPolicyAgent.jl/workflows/CI/badge.svg)](https://github.com/JuliaComputing/OpenPolicyAgent.jl/actions?query=workflow%3ACI+branch%3Amain) +[![codecov.io](http://codecov.io/github/JuliaComputing/OpenPolicyAgent.jl/coverage.svg?branch=main)](http://codecov.io/github/JuliaComputing/OpenPolicyAgent.jl?branch=main) -The OPA command line is made available in the `OpenPolicyAgent.CLI` module. To use, import the module. E.g.: +[Open Policy Agent (OPA)](https://www.openpolicyagent.org/) is an open-source, cloud-native policy engine that allows organizations to declaratively enforce policies across their software stack. It provides a unified, flexible, and efficient way to implement and manage policies for access control, security, and compliance in modern, dynamic environments. -```julia -julia> using OpenPolicyAgent +This package provides a Julia interface to the OPA server, and the client APIs to interact with the server. It also includes a command-line interface to the OPA command-line tool. -julia> import OpenPolicyAgent: CLI - -julia> ctx = CLI.CommandLine(); - -julia> CLI.opa(ctx; help=true); -An open source project to policy-enable your service. - -Usage: - opa [command] - -Available Commands: - bench Benchmark a Rego query - build Build an OPA bundle - capabilities Print the capabilities of OPA - check Check Rego source files - completion Generate the autocompletion script for the specified shell - deps Analyze Rego query dependencies - eval Evaluate a Rego query - exec Execute against input files - fmt Format Rego source files - help Help about any command - inspect Inspect OPA bundle(s) - parse Parse Rego source file - run Start OPA in interactive or server mode - sign Generate an OPA bundle signature - test Execute Rego test cases - version Print the version of OPA - -Flags: - -h, --help help for opa - -Use "opa [command] --help" for more information about a command. -``` - -# OPA Server - -The `OpenPolicyAgent.Server` module includes methods to help start the OPA server, -monitor it for failures, and restart when required. - -```julia -function start_opa_server(root_path) - opa_server = OpenPolicyAgent.Server.MonitoredOPAServer( - joinpath(root_path, "config.yaml"), - stdout = joinpath(root_path, "server.stdout"), - stderr = joinpath(root_path, "server.stderr"), - ) - OpenPolicyAgent.Server.start!(opa_server) - return opa_server -end - -start_opa_server("/tmp/opaserver") -``` - -# OPA Client - -OPA exposes domain-agnostic APIs that your service can call to manage and enforce policies. Read this page if you want to integrate an application, service, or tool with OPA. The REST APIs are grouped into the following categories: - -- **Policy API** - manage policy loaded into the OPA instance. -- **Data API** - evaluate rules and retrieve data. -- **Query API** - execute adhoc queries. -- **Compile API** - access Rego’s Partial Evaluation functionality. -- **Health API** - access instance operational health information. -- **Config API** - view instance configuration. -- **Status API** - view instance status state. - -The `OpenPolicyAgent.Client` module includes methods to help interact with the OPA server using the OpenAPI client. - -```julia -opa_client = OpenPolicyAgent.Client.DataApi(openapi_client) - -response, _http_resp = OpenPolicyAgent.Client.get_document( - opa_client, - "policies/server/rest/allowed" -); -@test response.result == false -``` - -OpenAPI [API Documents](src/client/README.md) give more details on the API methods. +[![](https://img.shields.io/badge/docs-latest-blue.svg)](https://JuliaComputing.github.io/OpenPolicyAgent.jl) diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..378eac2 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +build diff --git a/docs/Manifest.toml b/docs/Manifest.toml new file mode 100644 index 0000000..d6e2a93 --- /dev/null +++ b/docs/Manifest.toml @@ -0,0 +1,119 @@ +# This file is machine-generated - editing it directly is not advised + +julia_version = "1.9.2" +manifest_format = "2.0" +project_hash = "e0c77beb18dc1f6cce661ebd60658c0c1a77390f" + +[[deps.ANSIColoredPrinters]] +git-tree-sha1 = "574baf8110975760d391c710b6341da1afa48d8c" +uuid = "a4c015fc-c6ff-483c-b24f-f7ea428134e9" +version = "0.0.1" + +[[deps.Base64]] +uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f" + +[[deps.Dates]] +deps = ["Printf"] +uuid = "ade2ca70-3891-5945-98fb-dc099432e06a" + +[[deps.DocStringExtensions]] +deps = ["LibGit2"] +git-tree-sha1 = "2fb1e02f2b635d0845df5d7c167fec4dd739b00d" +uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae" +version = "0.9.3" + +[[deps.Documenter]] +deps = ["ANSIColoredPrinters", "Base64", "Dates", "DocStringExtensions", "IOCapture", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"] +git-tree-sha1 = "39fd748a73dce4c05a9655475e437170d8fb1b67" +uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +version = "0.27.25" + +[[deps.IOCapture]] +deps = ["Logging", "Random"] +git-tree-sha1 = "d75853a0bdbfb1ac815478bacd89cd27b550ace6" +uuid = "b5f81e59-6552-4d32-b1f0-c071b021bf89" +version = "0.2.3" + +[[deps.InteractiveUtils]] +deps = ["Markdown"] +uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240" + +[[deps.JSON]] +deps = ["Dates", "Mmap", "Parsers", "Unicode"] +git-tree-sha1 = "31e996f0a15c7b280ba9f76636b3ff9e2ae58c9a" +uuid = "682c06a0-de6a-54ab-a142-c8b1cf79cde6" +version = "0.21.4" + +[[deps.LibGit2]] +deps = ["Base64", "NetworkOptions", "Printf", "SHA"] +uuid = "76f85450-5226-5b5a-8eaa-529ad045b433" + +[[deps.Logging]] +uuid = "56ddb016-857b-54e1-b83d-db4d58db5568" + +[[deps.Markdown]] +deps = ["Base64"] +uuid = "d6f4376e-aef5-505a-96c1-9c027394607a" + +[[deps.Mmap]] +uuid = "a63ad114-7e13-5084-954f-fe012c677804" + +[[deps.NetworkOptions]] +uuid = "ca575930-c2e3-43a9-ace4-1e988b2c1908" +version = "1.2.0" + +[[deps.Parsers]] +deps = ["Dates", "PrecompileTools", "UUIDs"] +git-tree-sha1 = "716e24b21538abc91f6205fd1d8363f39b442851" +uuid = "69de0a69-1ddd-5017-9359-2bf0b02dc9f0" +version = "2.7.2" + +[[deps.PrecompileTools]] +deps = ["Preferences"] +git-tree-sha1 = "9673d39decc5feece56ef3940e5dafba15ba0f81" +uuid = "aea7be01-6a6a-4083-8856-8a6e6704d82a" +version = "1.1.2" + +[[deps.Preferences]] +deps = ["TOML"] +git-tree-sha1 = "7eb1686b4f04b82f96ed7a4ea5890a4f0c7a09f1" +uuid = "21216c6a-2e73-6563-6e65-726566657250" +version = "1.4.0" + +[[deps.Printf]] +deps = ["Unicode"] +uuid = "de0858da-6303-5e67-8744-51eddeeeb8d7" + +[[deps.REPL]] +deps = ["InteractiveUtils", "Markdown", "Sockets", "Unicode"] +uuid = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb" + +[[deps.Random]] +deps = ["SHA", "Serialization"] +uuid = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c" + +[[deps.SHA]] +uuid = "ea8e919c-243c-51af-8825-aaa63cd721ce" +version = "0.7.0" + +[[deps.Serialization]] +uuid = "9e88b42a-f829-5b0c-bbe9-9e923198166b" + +[[deps.Sockets]] +uuid = "6462fe0b-24de-5631-8697-dd941f90decc" + +[[deps.TOML]] +deps = ["Dates"] +uuid = "fa267f1f-6049-4f14-aa54-33bafae1ed76" +version = "1.0.3" + +[[deps.Test]] +deps = ["InteractiveUtils", "Logging", "Random", "Serialization"] +uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40" + +[[deps.UUIDs]] +deps = ["Random", "SHA"] +uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4" + +[[deps.Unicode]] +uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5" diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 0000000..fb315d1 --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,5 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" + +[compat] +Documenter = "0.27" \ No newline at end of file diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 0000000..ac3e834 --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,23 @@ +import Pkg +Pkg.add("Documenter") + +using Documenter +using OpenPolicyAgent + +makedocs( + sitename = "OpenPolicyAgent.jl", + format = Documenter.HTML( + prettyurls = get(ENV, "CI", nothing) == "true" + ), + pages = [ + "Home" => "index.md", + "Client" => "client.md", + "Server" => "server.md", + "Command Line" => "commandline.md", + ], +) + +deploydocs( + repo = "github.com/JuliaComputing/OpenPolicyAgent.jl.git", + push_preview = true, +) diff --git a/docs/src/client.md b/docs/src/client.md new file mode 100644 index 0000000..1594eaf --- /dev/null +++ b/docs/src/client.md @@ -0,0 +1,25 @@ +# OPA Client + +OPA exposes domain-agnostic APIs that your service can call to manage and enforce policies. Read this page if you want to integrate an application, service, or tool with OPA. The REST APIs are grouped into the following categories: + +- **Policy API** - manage policy loaded into the OPA instance. +- **Data API** - evaluate rules and retrieve data. +- **Query API** - execute adhoc queries. +- **Compile API** - access Rego’s Partial Evaluation functionality. +- **Health API** - access instance operational health information. +- **Config API** - view instance configuration. +- **Status API** - view instance status state. + +The `OpenPolicyAgent.Client` module includes methods to help interact with the OPA server using the OpenAPI client. + +```julia +opa_client = OpenPolicyAgent.Client.DataApi(openapi_client) + +response, _http_resp = OpenPolicyAgent.Client.get_document( + opa_client, + "policies/server/rest/allowed" +); +@test response.result == false +``` + +OpenAPI [API Documents](https://github.com/JuliaComputing/OpenPolicyAgent.jl/blob/main/src/client/README.md) give more details on the API methods. diff --git a/docs/src/commandline.md b/docs/src/commandline.md new file mode 100644 index 0000000..ab3b8ad --- /dev/null +++ b/docs/src/commandline.md @@ -0,0 +1,42 @@ +# OPA Command Line + +The OPA (Open Policy Agent) command-line tool is a versatile utility that empowers users to interact with and manage OPA policies and data. It allows users to perform various tasks, such as evaluating policies, testing Rego expressions, and querying data, all from the command line. This tool is invaluable for policy development, debugging, and troubleshooting, providing an accessible way to work with OPA without the need for complex integration. It's an essential companion for developers and administrators working with OPA, simplifying the process of authoring, testing, and refining policies to ensure robust and consistent policy enforcement across software systems. + +The OPA command line is made available in the `OpenPolicyAgent.CLI` module. To use, import the module. E.g.: + +```julia +julia> using OpenPolicyAgent + +julia> import OpenPolicyAgent: CLI + +julia> ctx = CLI.CommandLine(); + +julia> CLI.opa(ctx; help=true); +An open source project to policy-enable your service. + +Usage: + opa [command] + +Available Commands: + bench Benchmark a Rego query + build Build an OPA bundle + capabilities Print the capabilities of OPA + check Check Rego source files + completion Generate the autocompletion script for the specified shell + deps Analyze Rego query dependencies + eval Evaluate a Rego query + exec Execute against input files + fmt Format Rego source files + help Help about any command + inspect Inspect OPA bundle(s) + parse Parse Rego source file + run Start OPA in interactive or server mode + sign Generate an OPA bundle signature + test Execute Rego test cases + version Print the version of OPA + +Flags: + -h, --help help for opa + +Use "opa [command] --help" for more information about a command. +``` diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 0000000..4f25860 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,7 @@ +# OpenPolicyAgent.jl + +[Open Policy Agent (OPA)](https://www.openpolicyagent.org/) is an open-source, cloud-native policy engine that allows organizations to declaratively enforce policies across their software stack. It provides a unified, flexible, and efficient way to implement and manage policies for access control, security, and compliance in modern, dynamic environments. OPA excels at decoupling policy decision logic from application code, enabling fine-grained control over authorization, resource validation, and more. + +Its expressive policy language, called [Rego](https://www.openpolicyagent.org/docs/latest/#rego), allows users to define complex policies in a human-readable format. OPA is widely adopted in cloud-native ecosystems, helping organizations ensure consistent policy enforcement across services, APIs, and infrastructure components, making it a crucial tool for enhancing security and governance in modern software systems. + +This package provides a Julia interface to the OPA server, and the client APIs to interact with the server. It also includes a command-line interface to the OPA command-line tool. \ No newline at end of file diff --git a/docs/src/server.md b/docs/src/server.md new file mode 100644 index 0000000..e10157d --- /dev/null +++ b/docs/src/server.md @@ -0,0 +1,20 @@ +# OPA Server + +The OPA (Open Policy Agent) server is a critical component of the OPA ecosystem, serving as a central policy decision point. It's a standalone service that evaluates policies written in the Rego language and makes access control decisions based on those policies. The OPA server allows for efficient policy enforcement across various parts of a software stack, including microservices, APIs, and cloud infrastructure. It receives policy queries, typically in the form of JSON or structured data, and returns decisions, enabling fine-grained control over authorization and compliance. With its ability to scale and distribute policy evaluations, the OPA server plays a crucial role in ensuring consistent and dynamic policy enforcement in complex, modern, and cloud-native environments, enhancing security and governance across the entire system. + +The `OpenPolicyAgent.Server` module includes methods to help start the OPA server, +monitor it for failures, and restart when required. + +```julia +function start_opa_server(root_path) + opa_server = OpenPolicyAgent.Server.MonitoredOPAServer( + joinpath(root_path, "config.yaml"), + stdout = joinpath(root_path, "server.stdout"), + stderr = joinpath(root_path, "server.stderr"), + ) + OpenPolicyAgent.Server.start!(opa_server) + return opa_server +end + +start_opa_server("/tmp/opaserver") +``` From 5bd1e2bec8d57ce34360c9ffb4ac91a485c8a748 Mon Sep 17 00:00:00 2001 From: tan Date: Mon, 16 Oct 2023 08:24:56 +0530 Subject: [PATCH 2/2] add permissions for docs build --- .github/workflows/ci.yml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index db2b0f6..834d22b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -32,7 +32,7 @@ jobs: arch: x86 version: 1 steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - uses: julia-actions/setup-julia@v1 with: version: ${{ matrix.version }} @@ -55,9 +55,12 @@ jobs: files: lcov.info docs: name: Documentation + permissions: + contents: write + statuses: write runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - uses: julia-actions/julia-buildpkg@latest - uses: julia-actions/julia-docdeploy@latest env: