apache/pinot

Documentation for creating new tenants is incorrect

Open

#10580 opened on Apr 7, 2023

View on GitHub
 (6 comments) (0 reactions) (0 assignees)Java (4,937 stars) (1,234 forks)batch import
documentationgood first issue

Description

Existing steps to create a new tenant for e.g a server tenant: https://docs.pinot.apache.org/basics/components/tenant#server-tenant don't seem to be correct and invoking the actual API endpoint (/tenants) returns a 400 error even if there are untagged servers available in the environment. For e.g below payload

{ "tenantRole" : "SERVER", "tenantName" : "Demo", "offlineInstances" : 1, "realtimeInstances" : 0 } with a single untagged server available in cluster, yielded below error:

{ "code": 400, "error": "Cannot request more offline instances: 1 or realtime instances: 0 than total instances: 0" }

In addition there is no reason why you can't have more than one tag assigned to same server, so not sure if below in documentation is correct: "The creation will fail if number of untagged server nodes is less than offlineInstances + realtimeInstances."

When you do this through the Pinot console then it actually calls a diff. API endpt. (/updateTags) vs. what's in docs. @mayankshriv @npawar can we please review if above is accurate conclusion and fix the docs ?

Contributor guide

Tech stack
javarest api
Domain
documentationdatabase
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
needs maintainer response
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
mostly clear
Prerequisites
basic knowledge of Apache Pinotunderstanding of REST APIs
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60
Research direction
The issue reports incorrect documentation for creating tenants in Apache Pinot. The documentation at https://docs.pinot.apache.org/basics/components/tenant#server tenant describes steps that result in a 400 error. The correct API endpoint appears to be /updateTags rather than /tenants. The maintainers @mayankshriv and @npawar have been asked to review. Fixing the documentation requires verifying the correct endpoint and payload, and updating the docs accordingly. The relevant source files for the API and docs need to be identified in the repository.